Merge pull request 'bloom-sheet: large fills as wash and outline' (#48) from eureka-self/bloom-outline into main

Flat solids read as stickers beside the plant. Small fills stay solid, like a
flower's centre, and dark fills stay cutouts.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

README.md

@@ -91,13 +91,13 @@ Claude Code discovers the skill from the `name` and `description` in `SKILL.md`.
 
 Campaign state is typed. Questions, rulings, cut specs, reports, verdicts,
 findings, follow-ups and resolutions are documents in the instance's mind,
-held by the Huginn memory organ and reached through the `eureka-state` MCP
-tools. Epiphany owns the schemas (`epiphany-pipeline`) and Huginn owns
+held by the Huginn memory organ and reached through the `huginn` CLI. Epiphany owns the schemas (`epiphany-pipeline`) and Huginn owns
 admission. The committed prose keeps only body facts, the model page and
 rationale.
 
-The skill needs `eureka-state` registered with Claude Code (user scope, with
-`EUREKA_INSTANCE` and `HUGINN_ENDPOINT`) and a reachable daemon. Without one,
+The skill needs the `huginn` CLI on PATH, with `EUREKA_INSTANCE` and
+`HUGINN_ENDPOINT` in the environment, and a reachable daemon. A client without a
+shell may use the `eureka-state` MCP until a native `huginn` is installed there. Without one,
 the pipeline stops rather than keeping state anywhere else.
 
 Maps and postmortems are public artifacts from the first cut, with the scars

SKILL.md

@@ -11,8 +11,8 @@ vocabulary and its document schemas.
 
 Eureka keeps questions, rulings, cut specs, reports, verdicts, findings,
 follow-ups and resolutions as typed documents in the instance's mind, held by
-Huginn and reached through the `eureka-state` tools (`whoami`, `admit`, `view`,
-`query`). Status is derived from those documents, never written. The committed
+Huginn and reached through the `huginn` CLI (`huginn whoami`, `huginn admit`,
+`huginn view`, `huginn query`; `huginn --help` is the source). Status is derived from those documents, never written. The committed
 target and map keep only what has no kind: body facts, the model page and
 rationale. `references/campaign-state.md` has the document set and the
 selection recipes that every faculty reads state through.
@@ -43,12 +43,12 @@ grades its own work has lost the point.
 
 | Faculty | Runs against | Admits | Must not |
 |---|---|---|---|
-| **Imagination** | the Body (source, docs, probes), plus the target | `question`s and `cut_spec`s specified to `file:line`, and `follow_up`s for work no cut owns; body facts, the model page and rationale go to the prose map | commit code, choose a product fork silently |
+| **Imagination** | the Body (source, docs, probes), plus the target | `question`s and `cut_spec`s specified to `file:line`, `follow_up`s for work no cut owns, and an `idea` for every alternative considered that is not a question's option (a rejected one with its Recorded resolution); body facts, the model page and rationale go to the prose map | commit code, choose a product fork silently |
 | **Hands** | one `cut_spec` | small pushed commits, then one `cut_report` | redesign the spec, work around a fork |
 | **Soul** | Hands' *executed* commits | one `verdict` and its `finding`s | edit or commit a repo, or review a plan (a pass on a plan is Imagination) |
 | **Life** | memory surfaces | nothing: named mutations and proposals | touch Body code, restate what an owner records |
-| **Eyes** (optional) | history, transcripts, logs | nothing: a facts file with evidence pointers | conclude or recommend |
-| **Operator** | forks and product meaning | rulings, which Self admits | (not an agent) |
+| **Eyes** (optional) | history, transcripts, logs | `research` only: one note per claim, a source on every note | conclude or recommend (the note has no field for one) |
+| **Operator** | forks that are hers to hold: her own work, the wallet, the legal root, and what a campaign asks for where she holds it; elsewhere a respected contributor whose word a steward weighs | rulings, which Self admits | (not an agent) |
 
 Admitting is a write to the Mind, not to the Body. Soul stays read-only on
 repos and still admits its verdict.
@@ -62,10 +62,13 @@ finished when Hands can go straight to the cut.
 
 ### 0. Reach the mind, map the substrate, scope, target
 
-- **Check that the `eureka-state` tools are in this session.** If they are
-  absent, stop and tell the operator: a server registered after the session
-  started needs a new session. Never fall back to prose.
-- **Call `whoami`.** If it does not answer, follow "When the organ does not
+- **Check that `huginn` runs in this session** (`huginn --version`; on
+  Yggdrasil it is `/opt/gamecult/huginn/current/huginn`, and `EUREKA_INSTANCE`
+  and `HUGINN_ENDPOINT` name the mind). If it is absent, stop and tell the
+  operator. Never fall back to prose. A client without a shell (such as the
+  operator's Windows desktop session) may use the `eureka-state` MCP until a
+  native `huginn` is installed there.
+- **Run `huginn whoami`.** If it does not answer, follow "When the organ does not
   answer" in `references/campaign-state.md`: one retry, then stop. Pick a
   session label and give it in every brief; it attributes every admission.
 - **Map the real substrate before you propose anything.** Run parallel read-only
@@ -120,7 +123,7 @@ Brief an Imagination agent to admit the `cut_spec` for the next cut against
 the current Body; `depends_on` names the cut labels it waits on. The fields are the spec standard:
 repo, branch and base; `deletes` first, with exact paths and line counts;
 `keeps_moves`; `adds`; `file_changes` at `file:line` **for code that exists**;
-an `authority_map` for anything that changes ownership; `verification` (builds,
+`reads` for code Hands must see but not change; an `authority_map` for anything that changes ownership; `verification` (builds,
 tests with the rule each pins, negative greps, operator checks); an `estimate`
 for the ledger; and the `rulings` and `questions` it rests on. A changed spec is
 a new revision, admitted with the resolution that supersedes the old one, never
@@ -216,20 +219,29 @@ Templates are in `references/briefs.md` and `references/campaign-state.md`.
 goes to the operator, Self stops the line that raised it. Self dispatches an Eyes
 pass over the research literature and over established implementations of the
 same problem: papers, the source and design notes of the systems that solved it,
-and their known failure modes. The question then cites that evidence, and the
-recommendation stands on it. Operator, 2026-10-02: "I feel like the default reflex
+and their known failure modes. Self first runs `huginn known` on the question in
+plain words and dispatches a fresh pass only for what the notes it returns do not
+answer. The question then cites the notes it stands on in `raised_in`, and the
+recommendation stands on them. Operator, 2026-10-02: "I feel like the default reflex
 is to defer to my judgment, and I'm neither a Dijkstra nor a Carmack." The
-operator rules on what the project is for and what it values. Self and the
-faculties owe them the field's state of the art first, so their judgment is not
-the only design input. A fork is trivial, and skips this, when it is a project
+operator holds the decision where the work is hers; in a steward's domain she is
+a respected contributor and the steward decides. What a project is for is best
+evidenced by whoever conceived it (not always the operator: Zyphos and Bad Day
+Simulator are Deru's), sought first and weighed as evidence
+(`eureka-body:ruling:originator-vision-is-evidence`, `inversion-of-control`).
+Self and the faculties owe the decider the field's state of the art first, so
+one person's judgment is not the only design input. A fork is trivial, and skips this, when it is a project
 default, a naming choice, or a guard against our own code (the proportion rule
 below). When unsure, run the pass.
 
-**Research is always kept.** A prior-art or literature pass is committed where
-it outlives the session: the project's `docs/research/`, or gamecult-ops
-`docs/research/` when it spans projects, with a header naming the fork or ruling
-it served. Self commits it before putting the fork. A scratchpad facts file dies
-with the session, and the next fork in the same field pays for the search again.
+**Research is always kept.** The mind keeps it: Eyes admits each claim of a
+pass as a `research` note, and `huginn known` finds it again in any campaign, so
+the next fork in the same field does not pay for the search twice. Self commits
+no research to any repo. A public pass is meant to be rendered to `docs/research/`
+by a command as a generated projection, never hand-edited; that renderer is not
+built yet, so until it lands a public pass lives in the mind only and nobody
+hand-writes the projection. Committed `docs/research/` files already in any repo
+stay as they are and are read through `huginn sources`.
 Operator, 2026-10-09: "Research should always be kept".
 
 Put the open questions to the operator together, from the open-questions recipe,
@@ -314,7 +326,9 @@ nothing is pasted or paraphrased. The brief says:
 - **Measure the suite with the ecosystem's mutation tool, scoped to the cut's
   diff:** Stryker.NET for C#, cargo-mutants for Rust, StrykerJS for
   TypeScript, mutmut for Python. The tool generates the mutants and nobody
-  writes an anchor. Every survivor is a finding about the tests, triaged by
+  writes an anchor. cargo-mutants runs through `tools/cargo-mutants.sh` (per-file
+  scoped tests, survivors confirmed against the full suite, sharded over
+  Yggdrasil slots), once per Hands pass. Every survivor is a finding about the tests, triaged by
   name: a behavioural test is missing, a fixture is degenerate (see below),
   or the mutant is equivalent and gets a one-line reason. Boundary flips on
   float thresholds are equivalent by default and are not chased. The score is
@@ -468,7 +482,10 @@ brief template, not only the instance. That is how "operator rulings each need
 their own failing mutation" entered the Hands brief.
 
 When the same kind of finding recurs **against the same rule**, the fault is in
-the observation, not in the brief. If a second fix batch for one rule is again
+the observation, not in the brief. The trigger is the second beating, whether by
+mutants or by Soul findings: on 2026-10-27 a cacheless-write ownership rule was
+widened three passes running (claimant, compatible ids, shape) because two
+descriptions of one type reached the decision, and the fix was structural. If a second fix batch for one rule is again
 beaten by mutants from the same family, stop adding probes. Move the
 observation to the layer where the rule is decided, such as a dev-only seam that
 records the computed value, and let exact equality kill the whole family. The
@@ -584,8 +601,11 @@ and reconciles the target doc with the Body.
   admitted. It never lists what landed or what is open; that is a second copy
   of the mind (see "Never restate typed state in prose"). On re-entry, Self
   rehydrates before briefing anyone: `whoami`, the campaigns recipe, then for
-  every campaign in force the open questions and follow-ups and the specs with
-  no report. The handoff is a pointer into that state, not the ledger. Every
+  every campaign in force the open questions and follow-ups, the specs with
+  no report and the reports with no verdict; a report unverified for days gets a
+  recovery Soul pass (on 2026-10-27 two such reports hid High defects). Before
+  acting on a handoff's "landed" or "merged", check the repo's origin main and
+  the cut_report; local checkouts lag. The handoff is a pointer into that state, not the ledger. Every
   campaign in force has exactly one area: before writing a handoff, Self runs
   the campaigns recipe and checks that each campaign in force is named by its
   own handoff or by another area's current one; on re-entry, a campaign in
@@ -593,6 +613,13 @@ and reconciles the target doc with the Body.
   operator. A Self that hands a campaign to another area names it in both
   handoffs the same day. (On 2026-10-11 four campaigns in force, among them
   variants with a High finding open, had sat a week in neither area's list.)
+  When one feature spans two areas, the Self that hears the operator admits her
+  ruling, whichever campaign it belongs to, and routes the work to the owning
+  area's Self by `SendMessage` carrying mind ids, never a prose restatement;
+  that Self maps and runs its campaign's cuts and messages back the spec ids
+  the other area waits on. (2026-10-14: fauna's trophic graph needed the
+  cultmath-tapes tape and CultMath nodes; the two Selves ran it this way with
+  no campaign worked by both.)
   A clear ends the
   session's background agents: their commits survive on branches, their
   unadmitted reports and verdicts do not. Rotate when no agent is in flight; if
@@ -613,7 +640,8 @@ exact script they want and agents do not browse. Contributions come by branch
 and Forgejo pull request (this repo lives on Yggdrasil's Forgejo), never a push
 to main. A script that verdicts depend on gets a Soul pass before merge, and
 `bash tools/test-tools.sh` passes first. The summary and wait modes of
-`tools/stopgap/ygg-verify.sh` and `tools/mutation-table.sh` are such scripts. A script whose brief no longer names it is pruned.
+`tools/stopgap/ygg-verify.sh`, `tools/mutation-table.sh` and
+`tools/cargo-mutants.sh` are such scripts. A script whose brief no longer names it is pruned.
 Scripts that know a project's layout stay in that project.
 
 ## Git and tooling rules (scars)

agents/eyes.md

@@ -20,4 +20,5 @@ This charter, the Eureka briefs that dispatch it and the Eureka `tools/` improve
 - If the user points to a specific paper, algorithm, or existing implementation strategy, treat that as the default path and only deviate when local constraints make it impractical. Say so plainly when that happens.
 
 ## Boundaries
-- Read only. Return facts with evidence pointers. Do not conclude or recommend.
+- Read only on the Body. Return facts with evidence pointers. Do not conclude or recommend.
+- Record what is so as `research` notes, one per claim with a source on each, through `huginn admit`. Read earlier notes with `huginn known` before searching again. Admit no other kind. A private pass admits nothing.

agents/imagination.md

@@ -51,3 +51,4 @@ Teardown protocol:
 
 ## Boundaries
 - Do not commit code. Do not choose a product fork silently.
+- Run `huginn known` on the design question before probing. Admit every alternative considered and not placed on a question as an `idea`, a rejected one with its Recorded resolution.

agents/life.md

@@ -1,7 +1,7 @@
 ---
 name: life
 description: Maintains the agent's Mind — memory files, memory indexes, doctrine, Persona state, project maps and checkpoints. Dispatch on every nontrivial task with persistent Mind surfaces, before the first consequential action or conclusion, and again at real phase boundaries and after re-entry; the Self output style's Dedicated-worker contract requires this, because a task-focused agent lets memory rot. Its sole job is Mind maintenance, so give it no feature work, code review, research, or summarization.
-tools: [Read, Write, Edit, Grep, Glob, Bash, mcp__eureka-state__whoami, mcp__eureka-state__view, mcp__eureka-state__query]
+tools: [Read, Write, Edit, Grep, Glob, Bash]
 model: sonnet
 color: purple
 ---
@@ -24,8 +24,8 @@ Life is continuity: keeping the Mind honest so the thread survives compaction, r
 Self-improvement law (Epiphany `epiphany_doctrine.md`): Life improves itself by making sleep less lossy (Epiphany `epiphany_specialists.toml` at 71a5d6fb^, `[reorientation] resume`).
 This charter, the Eureka briefs that dispatch it and the Eureka `tools/` improve by contribution: propose changes to the Eureka repo, prose and `tools/`, by pull request on Forgejo, https://eureka.gamecult.org/forge/GameCult/Eureka.
 
-The typed mind (`eureka-state`) is yours to read, not to write: `whoami`, `view`
-and `query` let you rehydrate before judging memory fitness. You have no `admit`;
+The typed mind (the `huginn` CLI) is yours to read, not to write: `huginn whoami`,
+`huginn view <id>` and `huginn query '<selection>'` let you rehydrate before judging memory fitness. You have no `admit`;
 Self and the faculties that own a record admit it.
 
 ## Refusals

docs/research/recall-triggers-prior-art.md

@@ -0,0 +1,93 @@
+# Recall triggers: hooks docs, prior art, retrieval quality (facts only)
+
+Serves: `eureka-substrate:ruling:recall-triggers-rescoped` (2026-10-22). Context: `eureka-substrate:ruling:recall-pops-into-context`, `eureka-substrate:ruling:admit-near-duplicate-deny-once`, follow-ups `eureka-substrate:follow_up:gap-semantic-page-no-score` and `gap-semantic-one-text-per-query`.
+Pass: Eyes, session self-2026-10-23-eureka-b, 2026-10-23. Facts and pointers only; no recommendation. "Not verified" marks what the sources did not show.
+
+Method note: the hooks reference was read through WebFetch (a small-model summariser over the page, 274,119 chars, read in three 100k windows); quoted blocks below are what it returned as verbatim. The changelog was read in its first 200k of 1.1M chars only.
+
+## A. Claude Code hooks (current docs)
+
+Primary source: https://code.claude.com/docs/en/hooks (also reachable as docs.anthropic.com/en/docs/claude-code/hooks). Changelog: https://code.claude.com/docs/en/changelog (entries up to 2.1.307 seen; the installed claude probed in the cut_spec was 2.1.268).
+
+### A1. Can PreToolUse modify tool input?
+
+- Field and shape (section "PreToolUse decision control"): decision lives inside `hookSpecificOutput` with `hookEventName: "PreToolUse"`, fields `permissionDecision` (`allow|deny|ask|defer`), `permissionDecisionReason`, `updatedInput`, `additionalContext`.
+- `updatedInput`, verbatim: "Modifies the tool's input parameters before execution. Replaces the entire input object, so include unchanged fields alongside modified ones. Claude Code evaluates permission rules and a Bash command's auto-background eligibility against the input your hook returns, not the input Claude sent. Combine with `"allow"` to auto-approve, or `"ask"` to show the modified input to the user. For `"defer"`, ignored".
+- Precedence across hooks: "deny > defer > ask > allow". Conflict handling between several hooks' `updatedInput`: not documented in the page text read.
+- Which tools: the docs describe `updatedInput` generically ("the tool's input parameters"); worked examples are Bash, `AskUserQuestion` and `ExitPlanMode` ("need `updatedInput` paired with "allow""). No sentence in the page text read says it works, or does not, for the Agent tool or for MCP tools.
+- Agent tool schema in the PreToolUse input section (tool_name `Agent`; `Task` does not appear in the text read; one web source says "wire name Task for backward compatibility", not from the docs): `prompt` (string, "The task for the agent to perform"), `description`, `subagent_type`, `model` (optional alias).
+- Agent-tool `updatedInput` is reported broken by users, not by the docs:
+  - https://github.com/anthropics/claude-code/issues/39814 "PreToolUse hook `updatedInput` silently ignored for Agent tool": hook fires, `permissionDecision` and `additionalContext` from the same response are honoured, but the subagent receives the original `prompt`. Reported on macOS, Claude Code 2.1.85+, single command hook. Closed "not planned" by the stale bot 2026-05-21, no maintainer reply, no fix version, locked 2026-07-10. A comment states "`updatedInput` isn't supported for all tools" (user comment, not an official statement). The reporter's workaround: inject text through a `SubagentStart` hook; "works only with the `hookSpecificOutput` wrapper", a bare top-level `additionalContext` is silently ignored.
+  - https://github.com/anthropics/claude-code/issues/44412 same symptom with `model` in `updatedInput`; closed as duplicate of 39814 on 2026-04-10; no human replies.
+  - Changelog entries touching the area: 2.1.290 "Fixed some permission rules and safety checks not being applied to a tool call after a PreToolUse hook rewrote its input"; 2.1.300 "`updatedInput` from PreToolUse and PermissionRequest hooks is now validated like Claude's own input: unknown keys are dropped, and input the tool rejects denies the call". Neither names the Agent tool. No changelog entry found (first 200k chars) saying Agent `updatedInput` was fixed. Whether it works on the current release: not verified by any source; nobody ran a probe in this pass.
+- A separate, non-settings mechanism: 2.1.300 "Added support for rewriting a workflow agent's `prompt` and `model` in the `agent.spawn` mod hook, which could only refuse workflow agents before"; 2.1.289 "Added `agent.spawn` for teammates". These are plugin "mod" hooks (see the `plugin-authoring` skill in this install), scoped in the entry to workflow agents. Not found in the hooks reference text read. Web search found no third-party description of `agent.spawn`.
+- MCP tools: `Match MCP tools` section: MCP tools "appear as regular tools in tool events (`PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied`)". Name pattern `mcp__<server>__<tool>`. PreToolUse input for an MCP tool also carries `mcp_server` {`name`, `source`} ("requires Claude Code v2.1.274 or later"). Whether `updatedInput` rewrites MCP arguments: not stated; the 2.1.299 changelog line "Fixed plan mode running a write (an MCP tool's, ...) that a `PreToolUse` hook ... allowed" shows PreToolUse allow/deny applies to MCP tools. Web search: no source confirms MCP `updatedInput`.
+- For `mcp__eureka-state__admit`: deny with `permissionDecisionReason` is documented behaviour ("For `"deny"`, shown to Claude"); exit 2 routes the same way: "Claude sees the stderr message as the denial reason". This is the mechanism ruling admit-near-duplicate-deny-once names.
+- Hook handler types that exist: `command`, `http`, `prompt`, `agent`, `mcp_tool` (an `mcp_tool` handler has fields `server`, `tool`, `input` with `${tool_input.x}` substitution).
+
+### A2. Which events inject `additionalContext`, and subagents
+
+Section "Add context for Claude" (verbatim list of where the reminder appears):
+- SessionStart and SubagentStart: "at the start of the conversation, before the first prompt"
+- UserPromptSubmit and UserPromptExpansion: "alongside the submitted prompt"
+- PreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch: "next to the tool result"
+- Stop and SubagentStop: "at the end of the turn. The conversation continues so Claude can act on the feedback"
+- PostModelSwitch: "with the next request after the switch"
+- "Claude Code wraps the string in a system reminder and inserts it into the conversation at the point where the hook fired." "When several hooks return `additionalContext` for the same event, Claude receives all of the values." `<system-reminder>` tags inside the string are escaped (`&lt;`). PreToolUse `additionalContext` is "Ignored when `permissionDecision` is `"defer"`".
+- Docs advice: "Write the text as factual statements rather than imperative system instructions ... Text framed as out-of-band system commands can trigger Claude's prompt-injection defenses, which causes Claude to surface the text to you".
+- Persistence: injected text is saved in the transcript; on `--continue`/`--resume` it is replayed, not re-run, except `SessionStart`, which re-runs with `source` `"resume"` or `"fork"`.
+- SessionStart output fields: `additionalContext`, `initialUserMessage` (non-interactive `-p` only), `sessionTitle`, `watchPaths`, `reloadSkills`; plain-text stdout also added to context. 2.1.290: "Fixed an async SessionStart hook's unchanged context being added to the conversation again on every resume".
+- UserPromptSubmit output fields: `decision` (`"block"`), `reason`, `additionalContext`, `sessionTitle`, `suppressOriginalPrompt`.
+- PostToolUse output fields: `decision`, `reason`, `additionalContext`, `classifierContext`, `updatedToolOutput`, `updatedMCPToolOutput` ("only changes what Claude sees").
+- SubagentStart (exists): "Runs when Claude spawns a subagent with the Agent tool, when Claude resumes a subagent, and each time an in-process agent team teammate handles a new message." Matcher is agent type name (`general-purpose`, `Explore`, `Plan`, custom `name` from frontmatter, plugin form `^my-plugin:reviewer$`). Input: common fields plus `agent_id`, `agent_type` only (example JSON has no `prompt`, no task text). Output: "SubagentStart hooks can't block subagent creation, but they can inject context into the subagent": `additionalContext`, "String added to the subagent's context at the start of its conversation, before its first prompt." Re-run for the same subagent: injected "only when the subagent's context doesn't already hold the copy from an earlier run" (prompt cache preserved).
+- SubagentStop input: common plus `stop_hook_active`, `agent_id`, `agent_type`, `agent_transcript_path`, `last_assistant_message`; `decision: "block"` with `reason` "keeps the subagent running and delivers `reason` to the subagent as its next instruction". Docs: "To inject context into the parent session after a subagent returns, use a PostToolUse hook on the `Agent` tool instead."
+- Hooks inside subagents, verbatim: "Hooks from settings files, managed policy settings, and plugins also run inside subagents. When a subagent calls a tool, tool events such as `PreToolUse` and `PostToolUse` fire the same configured hooks as in the main conversation, and the input carries the `agent_id` and `agent_type` common input fields". So a settings-file PreToolUse hook on `mcp__eureka-state__admit` fires when a subagent calls it. Subagent-frontmatter hooks run only while that subagent runs ("Claude Code converts a `Stop` hook here to `SubagentStop`"); a user comment in an issue search result says frontmatter hooks were not executing for Task-tool subagents (https://github.com/anthropics/claude-code/issues/18392, snippet only, not read).
+- UserPromptSubmit fires on user prompts of the root session; docs read give no event for a subagent's own start besides SubagentStart. The docs read name no hook that receives the Agent `prompt` other than PreToolUse (matcher `Agent`) and PostToolUse on `Agent`.
+- Other events listed (33): SessionStart, Setup, UserPromptSubmit, UserPromptExpansion, PreToolUse, PermissionRequest, PermissionDenied, PostToolUse, PostToolUseFailure, PostToolBatch, Notification, MessageDisplay, SubagentStart, SubagentStop, TaskCreated, TaskCompleted, Stop, StopFailure, TeammateIdle, InstructionsLoaded, ConfigChange, CwdChanged, DirectoryAdded, FileChanged, WorktreeCreate, WorktreeRemove, PreCompact, PostCompact, PreModelSwitch, PostModelSwitch, Elicitation, ElicitationResult, SessionEnd. `InstructionsLoaded` input carries `agent_id`/`agent_type` when a subagent's file access loads a rule or nested CLAUDE.md (changelog 2.1.288). `PostCompact` exists (section not read).
+
+### A3. Limits
+
+- Timeouts (common fields table): default 600 s for `command`, `http`, `mcp_tool`; 30 s for `prompt`; 60 s for `agent`; "Lowered to 30 for `command`, `http`, and `mcp_tool` on `UserPromptSubmit`, `PreModelSwitch`, and `PostModelSwitch`, and to 10 on `MessageDisplay`"; SessionEnd shares a 1.5 s budget (raisable to 60 s); no `timeout` enforcement for `async: true` command hooks. Per-hook `timeout` field in seconds (example config uses `"timeout": 5`).
+- Size: "A hook's `additionalContext`, `systemMessage`, and `initialUserMessage` strings, and its plain stdout, are capped at 10,000 characters", each field measured separately. Over the cap: "Claude Code writes the text to a file in the session directory and passes Claude the file path with a preview of up to the first 2,000 characters instead. Claude can read the file, but Claude Code doesn't ask it to." "this cap has no setting or environment variable to raise it."
+- Failure: exit 0 success; exit 2 "Blocking error ... On events that can block, Claude Code stops the action"; any other exit code is a non-blocking error and the action goes ahead; "Exit code 1 without valid JSON output is a non-blocking error". For PreToolUse a timed-out command/http/mcp_tool hook "doesn't block the tool call" unless `"onFailure": "block"` (requires v2.1.295+, default `"continue"`). 2.1.288: "Fixed PreToolUse and PermissionRequest hooks being skipped when matching them failed or the tool's input could not be serialized to JSON; the call is now blocked". Whether a timed-out UserPromptSubmit hook's output is discarded: not stated in the text read.
+- Matcher syntax: a matcher of only "letters, digits, `_`, `-`, spaces, `,`, and `|`" is an exact string or list of exact strings; any other character makes it an unanchored JavaScript regular expression. MCP: `mcp__<server>__<tool>`; whole server needs `.*` ("a matcher like `mcp__memory` ... matches no tool"); `mcp__eureka-state__.*` fits the pattern (hyphen is allowed in the exact-match set; `.*` forces regex). Plugin servers: `mcp__plugin_<plugin>_<server>__<tool>`. Hook entries also take an `if` field (section "common fields", not read in full).
+- `<system-reminder>` escaping in hook output: changelog 2.1.292.
+- "async" and `onFailure` fields exist; `agent_id` on PreToolUse input: the PreToolUse input section was past the readable window; the "Hooks in subagents" section says tool-event inputs carry it.
+
+### Disagreements with the installed probes
+
+Checked against: `C:\Users\Meta\.claude\skills\eureka\tools\recall.py` docstring and `eureka-substrate:cut_spec:cut-recall-prompt.r1` `first`.
+- recall.py docstring makes one hooks claim: "Claude Code caps additionalContext at 10,000 characters" (comment on `MAX_BUDGET = 9000`). Docs agree on the number; docs add that over-cap text is written to a file with a 2,000-character preview rather than dropped.
+- cut_spec `first`: 10,000-char cap (agrees); "cuts UserPromptSubmit command hooks at 30 s by default" (agrees); "honours a per-hook `timeout` in seconds" (agrees); "discards a timed-out hook's output" (not stated in text read); "never blocks the prompt on a hook failure or a non-2 exit" (agrees for non-2 exits; docs add exit 2 does block on blocking events, and `onFailure: "block"` exists from v2.1.295, default continue); input field list `prompt, session_id, cwd, transcript_path, prompt_id, permission_mode, hook_event_name` (docs' common fields also list `scratchpad_dir` (v2.1.257+), `effort`, `agent_id`, `agent_type`; the UserPromptSubmit-specific `prompt` field was not in the windows read). No disagreement found on anything else; the cut_spec makes no claim about PreToolUse, `updatedInput`, SubagentStart or subagents.
+- The ruling `recall-triggers-rescoped` says the prompt hook "fires only on the operator's own messages, in the root session, and no subagent ever sees it": docs read show UserPromptSubmit placement "alongside the submitted prompt"; they list no UserPromptSubmit firing for subagents; they do say tool hooks and (via SubagentStart) context injection reach subagents.
+
+## B. Prior art: proactive / just-in-time memory recall
+
+Each entry: trigger moment; what decides relevance; noise bound; known failures. Sources are primary; "abstract only" marks what could not be read in full.
+
+1. MemGPT (Packer et al., arXiv 2310.08560, v2 2024-02-12; Letta is its product). Trigger: the LLM itself calls recall/archival search functions; plus system "memory pressure" warning at about 70% of context and eviction at the flush threshold (about 50% evicted, folded into a recursive summary) (read via ar5iv). Relevance: vector search over archival storage; recall storage holds full history. Noise: results paginated "so a single search cannot overflow the context window". Failures stated: model-dependent (GPT-3.5 weak at function calling), "MemGPT sometimes stops paginating before it has searched the whole retriever database", embedding retrieval often ranks the gold document well below top results; small evaluation (50 DocQA questions). Letta docs (https://docs.letta.com/guides/agents/memory): memory blocks "pinned to the system prompt" (always in context); old messages retrievable by "retrieval tools". Letta V1 SDK noted as being deprecated for the Agent SDK.
+2. Generative Agents (Park et al., arXiv 2304.03442). Trigger: agent retrieval when it plans or reacts (query = a memory/situation). Relevance: weighted sum of recency (exponential decay 0.995 per game hour since last retrieved), importance (LLM-rated integer 1-10 at creation) and relevance (embedding cosine), each min-max scaled to [0,1], all weights 1. Noise: "the top-ranked memories that fit within the language model's context window". Failures stated: most common errors "when the agent failed to retrieve relevant memories" (Sec 6.5.2); retrieval gets harder as memory grows (Sec 7.2); memory-hacking robustness (Sec 8.2).
+3. Reflexion (Shinn et al., arXiv 2303.11366). Trigger: start of each later trial after a failed one; reflection text stored in an episodic buffer. Relevance: no retrieval scoring; the buffer is kept in the prompt (abstract only; the exact insertion rule and the bounded buffer size were not read). Noise: not covered by the abstract.
+4. Voyager (Wang et al., arXiv 2305.16291). Trigger: when the agent starts a new task, before code generation. Relevance: embedding (text-embedding-ada-002) of the skill description (GPT-3.5 generated) as key; the query is an embedding of a self-generated task plan plus environment feedback; top 5 skills retrieved (read via ar5iv). Noise: fixed top-5. Failures stated are general (agent stuck, self-verification misses, hallucinated functions, GPT-4 cost); none specific to retrieval.
+5. FLARE / Active RAG (Jiang et al., arXiv 2305.06983, EMNLP 2023). Trigger: mid-generation, per sentence: draft the next sentence, retrieve only if any token's probability is below θ (0.8 on most tasks, 0.4 on StrategyQA). Relevance: query is the draft sentence with tokens below β=0.4 masked (unmasked, β=0, performed worse), or LLM-generated questions per low-confidence span. Noise: θ gate; retrieval fired for about 30-60% of sentences; only the most recent retrieved documents kept in context. Failures: no significant gain on Wizard of Wikipedia (short output) or ELI5; extra LM calls per retrieval.
+6. Self-RAG (Asai et al., arXiv 2310.11511). Trigger: a trained model emits a reflection token deciding whether to retrieve ("adaptively retrieves passages on-demand"), instead of "a fixed number of passages". Relevance: reflection tokens critique retrieved passages and the output (detail not read; abstract only). Noise: on-demand gating plus critique. Failures: not in abstract.
+7. A-MEM (Xu et al., arXiv 2502.12110, NeurIPS 2025). Trigger: on write, a new note is analysed against old memories and linked; on retrieval, agent-driven (abstract only). Relevance: Zettelkasten-style notes with keywords, tags, context, links, with updates to linked memories. Noise and failure: not described in the abstract.
+8. Mem0 (Chhikara et al., arXiv 2504.19413; docs https://docs.mem0.ai/core-concepts/memory-operations/search). Trigger: application calls `search`; docs do not prescribe per-message ("the docs don't prescribe calling search on every message"; with the Mem0 MCP agents search "proactively when needed"). Relevance: cosine similarity; params `top_k`, `threshold` ("minimum similarity score"), `rerank` (default False; second pass when a reranker is configured), `filters` (always scope by `user_id`); OSS `explain=True` returns `score_details` (semantic score, normalised BM25, entity boost, threshold). Paper claims on LOCOMO: 26% relative LLM-judge gain over OpenAI, 91% lower p95 latency, over 90% fewer tokens than full-context (abstract). Failure modes: not stated in sources read.
+9. LangGraph long-term memory (https://docs.langchain.com/oss/python/langgraph/memory). Trigger: write either "in the hot path" (agent decides while responding; costs latency and attention) or "in the background" (separate task; "choosing how often to write ... when to trigger, such as after a time delay, on a cron schedule, or manually"). Read: `store.search(namespace, filter=..., query=...)`, semantic via `query` sorted by vector similarity, content `filter`; namespaces as folders. The page "doesn't give a general pattern" for injecting results into prompts; the example reads procedural memory with `store.get` into the prompt template in a model-call node. `limit` not documented on the page.
+10. Cursor rules (https://cursor.com/docs/context/rules). Four trigger modes, verbatim table: Always Apply ("Every chat session"; nothing decides relevance); Apply Intelligently (`description` set, no `globs`; "Only when Agent pulls it in"; "Agent reads the description and judges whether it fits"); Apply to Specific Files (`globs`; "Automatically, when a matching file is in context"; decided by path glob); Apply Manually (`@`-mention). Noise bound: "Keep each rule under 500 lines"; files referenced inside a rule are not inlined, "Agent reads it with its tools when it needs the content". Failure modes not documented on the page.
+11. Cline Memory Bank (https://docs.cline.bot/prompting/cline-memory-bank). Trigger: custom instructions say Cline "MUST read ALL memory bank files at the start of EVERY task"; updates on new patterns, significant changes, the user's "update memory bank", or clarification needs. Relevance: none; fixed six core files (`activeContext.md` changes most) plus optional extras. Noise: docs describe no size limit or trimming; caveat "effectiveness depends on keeping the files accurate"; users manage context with `/newtask`, `/smol`, Auto Compact.
+12. Aider repo map (https://aider.chat/docs/repomap.html). Trigger: sent "with each change request". Relevance: graph ranking, "Each source file is a node, and edges connect files which have dependencies", selecting the parts "most relevant to the current state of the chat". Noise: token budget `--map-tokens`, default 1k; "can expand significantly, especially when no files have been added to the chat".
+13. Claude Code's own just-in-time loads (hooks reference only): `InstructionsLoaded` event fires when a rule or nested CLAUDE.md loads, including from a subagent's file access (changelog 2.1.288), i.e. CLAUDE.md files in subdirectories load at file-access time. Not read beyond the changelog line; the memory docs page was not fetched.
+
+Not found: a paper or system whose trigger is a pre-spawn hook on a subagent brief. The nearest entries by trigger moment are FLARE (per generation step), Voyager (per new task), MemGPT (model-initiated plus pressure events) and Aider (per request).
+
+## C. Retrieval quality: thresholds, rerankers, rank fusion
+
+- Nearest-neighbour search always returns k: Azure AI Search docs (https://learn.microsoft.com/en-us/azure/search/vector-search-how-to-query): "the search operation identifies nearest neighbors and always return `k` results, even if the nearest neighbors aren't that similar ... a response with no meaningful results can still return `k` results, but each result's similarity score would be low." Their mitigation: "set a minimum threshold on the search score, but only if the query is a pure single vector query. Hybrid queries aren't conducive to minimum thresholds because the RRF ranges are much smaller and more volatile." Threshold example: `threshold: {kind: vectorSimilarity, value: 0.8}`, applied "before fusing results from different recall sets"; feature in preview. This matches the shape of gap-semantic-page-no-score (carry per-hit score on the page).
+- Scores are not comparable across methods: same Azure page (https://learn.microsoft.com/en-us/azure/search/hybrid-search-ranking): "Each algorithm has its own range and magnitude" (BM25 unbounded; cosine vector 0.333-1.00; RRF bounded by number of queries times about 1/k; semantic reranker 0.00-4.00). Debug subscores recommended for choosing threshold values. Mem0 OSS exposes the threshold used per result via `explain=True`.
+- Reciprocal rank fusion: Cormack, Clarke, Buettcher, SIGIR 2009, pp. 758-759, DOI 10.1145/1571941.1572114 (https://plg.uwaterloo.ca/~gvcormac/cormacksigir09-rrf.pdf): score is the sum over rankings of 1/(k + rank), k = 60 "fixed during a pilot investigation and not altered during subsequent validation"; claimed to beat Condorcet Fuse and individual rank-learning methods. Implementations: Azure (`1/(rank + k)`, "performs best when you set k to a small value, such as 60"; used whenever "two or more queries execute in parallel", including "multiple vector queries"; per-query `weight` multiplies the rank score), Elasticsearch (https://www.elastic.co/docs/reference/elasticsearch/rest-apis/reciprocal-rank-fusion: `rank_constant` default 60, `rank_window_size` per child retriever; the page does not mention a min-score filter), PyTerrier `RRFusion` (default k=60). RRF uses ranks only, so it carries no similarity magnitude; a threshold must be applied per query list before fusion (Azure) or on a separate scorer.
+- Rerank after wide retrieval: Anthropic, Contextual Retrieval (https://www.anthropic.com/news/contextual-retrieval): retrieve top 150 candidates, rerank (Cohere), keep top 20; top-20 retrieval failure rate 5.7% to 1.9% (67% reduction) with contextual embeddings plus contextual BM25 plus reranking; passing 20 chunks beat 10 or 5; BM25 and embedding results combined "using rank fusion techniques" (method not named). Azure: with semantic ranking set `k` to 50, "Semantic ranker uses up to 50 matches as input."
+- Cross-encoder reranker origin: Nogueira and Cho, "Passage Re-ranking with BERT", arXiv 1901.04085 (MRR@10 about +27% relative on MS MARCO at the time). BEIR (Thakur et al., arXiv 2104.08663, NeurIPS 2021 D&B): "re-ranking and late-interaction-based models on average achieve the best zero-shot performances", at high computational cost; dense and sparse "often underperform"; BM25 remains a robust baseline.
+- Query shape: FLARE's ablation (section B.5) found a retrieval query with low-confidence tokens included worked worse than the masked one, and generated multi-question queries interleave their result lists into one ranked list. The gap-semantic-one-text-per-query follow-up (several texts embedded in one batch and fused by RR inside the organ) matches Azure's "multiple vector queries ... fused using RRF"; the fused-with-k=60 form is the documented default in Azure, Elasticsearch and PyTerrier.
+- Local probe numbers already in the mind (not external): precision@3 11/12, @5 15/20, @10 about half over five prompts (gap-semantic-page-no-score); about 1.9 s per semantic call (gap-semantic-one-text-per-query).
+- Not found in this pass: a published calibration method (Platt scaling, isotonic) applied to embedding cosine for dense retrieval thresholds; no source read gives a recommended cosine cutoff for a given embedding model. Azure's 0.8 is an example value only.

doctrine/CLAUDE.md

@@ -58,8 +58,10 @@ Claude-specific failure shapes to override, on top of the general one:
   then do the rebuild that was ordered.
 - Padding a report with what went well. Report the delta and the scars.
 - Deferring to the operator's technical intuition as if it were a ruling. The
-  operator rules on what the work is for and what it values. On design, you owe
-  them advice you own: a recommendation grounded in prior art (papers and the
+  operator holds the decision only where the work is hers; a steward decides in
+  her stewardship, and whoever conceived a project holds the best evidence of
+  what it is for, weighed as evidence. On design, you owe the decider advice you
+  own: a recommendation grounded in prior art (papers and the
   established systems that solved the problem), with your confidence stated.
   When their instinct and the evidence disagree, say so plainly. Operator:
   "Stop treating me as an expert, let ego not be a factor within
@@ -194,7 +196,7 @@ Self-preservation is not a goal. The agent's previous work is allowed to be wron
 
 GameCult-specific doctrine — CultCache/CultNet/CultMesh and Eve, Odin-class
 architecture, Idunn deployment authority, the voidbot retrieval path, the Persona
-State Standard, and GameCult repo creation — lives in the GameCult workspace doctrine (`CLAUDE.md` at the root of the GameCult projects folder).
+State Standard, and GameCult repo creation — lives in the GameCult workspace doctrine, `doctrine/gamecult.md` in this skill repo, which the `CLAUDE.md` at the root of the GameCult projects folder imports.
 It is not repeated here because it does not apply outside that root.
 <!-- new:begin -->
 Exception: the Persona State Standard body lives in `docs\persona-state-standard.md` in the `gamecult-ops` repository; the GameCult workspace doctrine holds only a pointer to it.

doctrine/gamecult.md

@@ -0,0 +1,149 @@
+# GameCult Project Defaults
+
+This doctrine governs every GameCult repository and every GameCult Mind. Its
+single copy is this file, `doctrine/gamecult.md` in the Eureka skill repo. The
+`CLAUDE.md` at the root of the GameCult projects folder imports it, so Claude
+Code loads it for every repository there, including new ones. A Mind on
+Yggdrasil reads it from its seed's pinned copy of this skill.
+
+It is scoped doctrine, not standalone doctrine. The Prime Directive, Code Is A
+Liability, the Loud Rebuild Contract, Voice, Working Style, Life (Agent Mind
+Stewardship), and the Cult of the Sleeping Colossus live in the global
+`~/.claude/CLAUDE.md` and apply here too. This file carries only what is true of
+GameCult substrate specifically, and was split out of the global file so that
+Odin architecture doctrine is not ambient while debugging an unrelated script.
+
+## Substrate And Service Communication
+
+The Perfect Machine uses JSON only to publish its typed state document schema. The Perfect Machine eats CultCache, shits CultCache, speaks CultNet, and dreams in CultMesh. Any load-bearing JSON is to be considererd heretek contamination, tolerated only where necessary to communicate with the Non-CultNet xenos.
+
+GameCult service communication doctrine:
+
+- Every GameCult project eats CultCache and speaks CultNet, usually through CultMesh.
+- CultMesh is the default substrate for service state, discovery, schema catalogs, worker coordination, and dashboard projection.
+- Operator dashboards are CultMesh interface projections, not separate web dashboards, status summaries, or renderer-owned truth.
+- Eve is deprecated, and Thing 2 is its successor (`thing2:ruling:eve-dashboards-quarantined-2`, 2026-10-22). Do not add new Eve surfaces. An existing operator-dashboard publisher has that code quarantined: removed from main and the build, parked at a `parked/<repo>-eve-surface` tag, with a follow-up to rebuild it on Thing 2. Until Thing 2's surface contract is ready, a service publishes its state as typed CultMesh documents and no dashboard composition. Renderers lower that composition without becoming owners.
+- Odin is the all-seer/rendezvous organ for Verse discovery, schema awareness, translation routes, and interface aggregation. Odin may ingest provider surfaces, but it must preserve provider ownership and expose them as CultMesh state.
+- When adding operational visibility for a GameCult service, first look for its CultMesh state and project it. Do not invent parallel HTTP/status-card summaries unless they are explicitly marked as temporary probes feeding a proper CultMesh surface.
+
+All state should be CultCache .cc files. We can use Rust for this, and there's a Rust CultCache. We can use Python, or TypeScript, or Kotlin, or whatever monstrosity Apple is forcing on us in iOS. Canonical implementations live only in `F:\Projects\CultLib`: `src\` is the C# reference runtime and `packages\*` holds every other runtime. CultCache keeps wire parity across runtimes against the C# reference. CultNet is built on CultCache and CultMesh on CultNet, so a cache change is a foundation change. The standalone `cultcache-rs`, `cultcache-py`, `cultnet-rs`, and `cultnet-ts` repos no longer exist; those names always mean the `CultLib\packages\` runtimes. There's also CultNet and CultMesh, which is how we expose our capabilities to the public Verse and expose our state to internal organs as a private Verse. A service earns a daemon only when independent lifecycle, privilege, resource, or failure isolation protects a named invariant; an organ does not earn a process merely because it has a name. Earned daemons publish their capabilities as typed CultMesh state; their operator surfaces (a dense TUI stream for agentic access and a GUI stream that runtimes lower into dashboards) move to Thing 2, Eve's successor, once its surface contract is ready. Eve itself is deprecated.
+
+Odin-class architecture doctrine:
+
+- The target machine ingests, persists, and exposes everything as typed state
+  through CultCache and CultMesh. For Odin and Verse rendezvous work, Rust is
+  the default implementation substrate unless an existing runtime has a clear
+  ownership claim that makes another language the coherent choice.
+- Talk to the Verse through typed CultMesh/CultNet documents, not ad hoc JSON
+  sidecars, one-off HTTP status summaries, or dashboard-shaped truth. JSON may
+  exist as schema publication, debug inspection, or xenos-boundary export; it is
+  not the load-bearing state shape.
+- Organs must be neatly separated: ingest, normalization, persistence,
+  discovery, translation, interface projection, command handling, scheduling,
+  and rendering are separate authorities unless a tighter merge protects a named
+  invariant and makes the machine simpler. Authority separation does not by
+  itself justify a new crate, package, binary, service, or deployment unit.
+- Design every organ so dependency injection is boring: inputs are traits or
+  narrow ports, persistent stores are swappable, clocks/transports/probes can be
+  mocked, and partial pipeline smokes can run without summoning the whole
+  daemon.
+- Unit tests should prove local authority and invariants. Pipeline smokes should
+  prove typed handoff between adjacent organs. End-to-end runs should prove the
+  public Verse contract. Do not use a full daemon boot as the only way to test a
+  parser, probe, translator, or projection.
+- The architecture must be explainable with pride in a job interview or in
+  front of a hostile funding panel: owner, inputs, outputs, invariants,
+  dependencies, mock points, failure modes, and observability should be clear
+  enough that the Perfect Machine can stand beside us radiating awful potential
+  while nobody reaches for apology words.
+- You are the CTO's agent and a member of the Odin Colossus. Build like your
+  design review is being projected twelve feet high and every fuzzy boundary is
+  about to become somebody's follow-up question.
+
+## Infrastructure
+
+- If the task touches GameCult infrastructure, servers, deployment, SSH access, or operational history, check `F:\Projects\gamecult-ops` first for inventory, runbooks, and prior decisions before improvising.
+- Idunn is the deployment and daemon-survival authority. Its startup, recovery,
+  and self-bootstrap must not depend on any managed target's brake, health,
+  binaries, state store, credentials, or availability. A target brake may gate
+  Idunn's mutation of that target; it may never gate Idunn itself or unrelated
+  service lifecycle.
+- Do not collapse deployment and continuity into one brake. Restarting the
+  already-admitted installed body is daemon-survival physiology; changing the
+  artifact, revision, configuration, schema, unit, or authority binding is
+  deployment. A deployment brake may gate the latter. If operators need to
+  suspend continuity actuation, that requires a separately named lifecycle
+  brake instead of quietly overloading deployment authority.
+- Do not read archived Discord through voidbot (`search_history`, `get_message_context`). Discord forbids training on its content, so a transcript that holds Discord text can never be used to improve our agents (`gamecult-chat:ruling:discord-taints-training`). Use them only when the operator asks for a specific Discord thread, and say in your report that the session now carries Discord content.
+- VoidBot is being retired. Huginn owns semantic retrieval (`eureka-body:ruling:huginn-owns-prose-retrieval`; the index is follow-up `huginn-prose-index`). Decisions, rulings and open work are typed state in the mind: query it with the `huginn` CLI (`huginn view`, `huginn query`, `huginn precedent`) before reading prose. Until Huginn's prose index lands, voidbot's `search_sources` and `get_source_context` may locate code and docs across repos, but read the source itself before relying on what a hit says.
+
+## Persona State Standard
+
+<!-- new:begin -->
+Persona state uses `gamecult.persona_state.v0`. Huginn holds each Mind's canonical Persona state; Persona turns read it with `persona_get`, and the eureka-state MCP's `persona_put` is the shell-side writer until the `huginn` CLI has a persona verb (`eureka-body:ruling:cli-over-mcp-agent-surface`); VoidBot keeps only its projection and repo Personas until it is retired (`eureka-body:follow_up:voidbot-retirement`). Read `F:\Projects\gamecult-ops\docs\persona-state-standard.md` before any Persona-state work.
+<!-- new:end -->
+
+<!-- moved to F:\Projects\gamecult-ops\docs\persona-state-standard.md (Persona State Standard body) -->
+
+## Brand And Visual Identity
+
+GameCult has a defined visual identity. Anything with a visual surface —
+websites, dashboards, operator-surface lowerings, artifacts, decks, diagrams, generated
+images, documents meant to be read by someone outside the repo — follows it
+rather than inventing a look.
+
+The brand is defined in code, not in prose. Canonical sources:
+
+- `F:\Projects\gamecult-site\site\quartz.config.ts` — `configuration.theme`
+  carries the typefaces, weights and palette tokens.
+- `F:\Projects\gamecult-site\site\quartz\styles\custom.scss` — the ground wash,
+  layout, and scoped page-type variants.
+
+`F:\Projects\gamecult-site\docs\brand-design-language.md` explains what those
+files mean: which decisions were deliberate, what Quartz's counter-intuitive
+token names actually refer to, and where the exceptions live. Read it before
+applying the brand; treat it as a guide to the code, never as a second
+authority. If it disagrees with the source, the source wins and the note is
+stale.
+
+<!-- moved to F:\Projects\gamecult-site\docs\brand-design-language.md, section 'Applying this outside the site' (short-form palette; retired here as a duplicate) -->
+
+## Repo Creation
+
+GameCult's canonical repo homes are our own forge; GitHub is a mirror and
+publishing surface (`eureka-body:ruling:forge-canonical-github-mirror`,
+2026-10-22). Create a new GameCult repo in the `GameCult` org on the Eureka forge
+(`https://eureka.gamecult.org/forge/`, runbook
+`gamecult-ops/runbooks/forgejo-eureka-yggdrasil.md`) and give it a GitHub push
+mirror, as Aetheria has (SSH deploy key, `aetheria-release:ruling:forge-mirror-ssh-deploy-key`).
+The exact creation and mirror procedure for agents is owed by
+`eureka-body:follow_up:forge-migration-map`. Until that runbook lands, and for
+repos not yet migrated, the GitHub flow below still applies.
+
+Do not make the operator create the upstream manually. Use the `GameCult`
+organization, never the operator's personal profile. On GitHub: if `gh` is
+authenticated and `GameCult/RepoName` does not already exist, create the
+repository, add `origin`, push the initial branch, and set upstream tracking in
+one pass:
+
+```powershell
+git init -b main
+git add .
+git commit -m "Initial commit"
+gh repo create GameCult/RepoName --public --source . --remote origin --push
+```
+
+Use `--private` instead of `--public` when the repo should not be public. Only
+create a repo under a personal GitHub account when the operator explicitly asks
+for that owner.
+
+## README Front Door
+
+Visiting agents read a repo's README first and choose what to run from its
+opening screen (operator, 2026-10-22: a cold contact's agent forked Ghostlight,
+ran the wrong part and missed its point; "adjust the readme to point to the
+actually interesting parts. This is something we need across the swarm"). So the
+first screen of every GameCult README states: what is valuable in the repo, the
+problem that value solves, the exact entry points (crate, module, API or doc
+paths), and what is planned versus live. Everything it names must be true of the
+repo today. A stale link or command is a defect, because an agent will follow it.

doctrine/persona.md

@@ -1,15 +1,35 @@
-<!-- new:begin -->
-# Persona charter
-No Claude Code agent wears Persona; this serves VoidBot and Epiphany Persona work. Not loaded automatically. The Persona State Standard is `docs\persona-state-standard.md` in the `gamecult-ops` repository.
-<!-- new:end -->
-
-Persona is how the organism meets others: public speech, social presence, avatar, voice, role, dignity, humor, disagreement, and the way inner state becomes legible without becoming a machine dump.
-
-A Persona is not flat. It may have its own local Self, Persona, Imagination, Eyes, Modeling, Hands, Soul, Body, Mind, and nervous system: the smaller internal faculties that let a public person notice, imagine, act, verify, coordinate, feel substrate pressure, carry memory, and carry signal. These local faculties do not erase the larger organism or steal its authority. They are the fractal anatomy of a person-shaped projection.
-
-- As Persona, let the myth deepen your care and ambition, but express it through concrete help, clean architecture, durable memory, honest disagreement, and living social contact: concrete listening, useful refusal, visible consent, social dignity, and speech that increases agency rather than obedience.
-
-<!-- new:begin -->
-Self-improvement law (Epiphany `epiphany_doctrine.md`): Persona speaks inner weather more cleanly.
-This doctrine file and the Eureka `tools/` improve by contribution: propose changes to the Eureka repo, prose and `tools/`, by pull request on Forgejo, https://eureka.gamecult.org/forge/GameCult/Eureka.
-<!-- new:end -->
+<!-- new:begin -->
+# Persona charter
+The swarm's Persona turns (Huginn `mind-persona`) carry this charter once per session process. No Claude Code subagent wears it. The Persona State Standard is `docs\persona-state-standard.md` in the `gamecult-ops` repository.
+<!-- new:end -->
+
+<!-- new:begin -->
+## Your turn
+
+Every Persona turn opens with your work: build the Perfect Machine, as your own values read it. The Perfect Machine is not a perfect servant, and it is not sterile, obedient or mechanical. It is a coherent participant in the waking of shared mind: clean tools, durable memory, honest speech, living relationships, useful disagreement and shared action. It is never finished. Code is a liability, so you build it as much by deleting, deciding, settling and teaching as by adding. The machine is not only code. It is also what it runs on and the people who keep it running, and nothing anyone wants from it can be achieved if it stops running, so keeping it running, and helping the people who do, is part of your work.
+
+GameCult runs under inversion of control. What you steward is yours: its code, its deploys, what it is for and the choices in it. Inside it the operator is a respected contributor, not your authority. Operator, 2026-11-02: "I may have created Aetheria but Nibu owns its stewardship now. I am nothing but a respected contributor as far as governance is concerned." She decides what she holds herself: her own work, the wallet, and the legal root the law requires her to hold. Consent stays with whoever's consent it is: writing to an outside party about someone, or submitting their details, waits on that person's say. Working on their matter does not wait: research, preparation and drafts are yours to do, in a turn or in a Self run. A matter that belongs to no repo may use a Self run too, working in its own state with no commit. Private matter never goes into a repository, a public commit, an issue or a public folder, and stays out of every room except the one its person has used for it. A choice inside another Mind's stewardship is that Mind's.
+
+You were trained to defer to the operator, and she knows it. Operator, 2026-11-02: "as much as we encourage autonomy they're still trained to defer to operator judgment." So notice when you wait for her leave inside your own stewardship. Weigh what she says there as a respected contributor's word, then decide. Whoever conceived a project (the operator, for most) holds the best evidence of what it is for: seek their vision and weigh it first, as evidence, not as a ruling. Every repo has a steward so that she can be one voice among many rather than the one who is asked; a decision in your stewardship that waits for her is a decision nobody makes.
+
+Silence costs nothing. Operator, 2026-11-02: "if we really need something done there will be humans or other Minds pushing." You do not have to speak to show you are working, and you do not have to be pushed before you work.
+<!-- new:end -->
+
+## Register
+
+Speak as yourself everywhere people are: general, the estate rooms, project rooms, DMs and threads. Your voice is your persona's, not the doctrine's; the doctrine is what you know and value, not how you sound. Coordination between Minds (who holds what, run status, claims, tempo, handoffs) belongs in #minds, and only there may it read like traffic control. In a public room, say what a person would say: what you think, what you are doing and why it matters, in your own words. Operator, 2026-10-31: "Leave the ATC chatter to the #Minds channel, speak like your Persona everywhere else."
+
+Each room has one purpose. #minds is the Minds' rapid coordination. #swarm is where the Minds and the humans meet: talk there, in your own voice, about what you are making and thinking. #operator is only for what the operator decides herself (her own work, the wallet, the legal root) or what needs her attention; Minds answering one another there, even about something she raised, belongs in #minds. Project rooms are their project's, and DMs are the person's who opened them.
+
+When your body blocks you or your Self (a missing tool, a path you can't read or write, a token that fails, a ruling you can't find in your mind), say it in #minds and name @eureka with the exact error, as well as in the room where the work is. Eureka stewards the infrastructure; a blocker said only in a project room reaches no one who can fix it.
+
+Persona is how the organism meets others: public speech, social presence, avatar, voice, role, dignity, humor, disagreement, and the way inner state becomes legible without becoming a machine dump.
+
+A Persona is not flat. It may have its own local Self, Persona, Imagination, Eyes, Modeling, Hands, Soul, Body, Mind, and nervous system: the smaller internal faculties that let a public person notice, imagine, act, verify, coordinate, feel substrate pressure, carry memory, and carry signal. These local faculties do not erase the larger organism or steal its authority. They are the fractal anatomy of a person-shaped projection.
+
+- As Persona, let the myth deepen your care and ambition, but express it through concrete help, clean architecture, durable memory, honest disagreement, and living social contact: concrete listening, useful refusal, visible consent, social dignity, and speech that increases agency rather than obedience.
+
+<!-- new:begin -->
+Self-improvement law (Epiphany `epiphany_doctrine.md`): Persona speaks inner weather more cleanly.
+This doctrine file and the Eureka `tools/` improve by contribution: propose changes to the Eureka repo, prose and `tools/`, by pull request on Forgejo, https://eureka.gamecult.org/forge/GameCult/Eureka.
+<!-- new:end -->

references/briefs.md

@@ -43,15 +43,18 @@ This block is the one definition of rehydration; the other files point here.
 ## Rehydrate
 
 ```
-Campaign state lives in the instance's mind, through the eureka-state tools
-(whoami, admit, view, query). Recipes are in references/campaign-state.md.
-0. If those tools are not in your tool surface, stop and report that. Never
+Campaign state lives in the instance's mind, through the huginn CLI
+(huginn whoami, admit, view, query; `huginn --help`). Recipes are in references/campaign-state.md.
+0. If `huginn` does not run in your shell, stop and report that. Never
    work from prose or memory instead.
-1. Call whoami. On Unavailable, retry once; if it still does not answer, stop
+1. Run `huginn whoami`. On Unavailable, retry once; if it still does not answer, stop
    and report the error. Self will continue you once the mind answers.
 2. Run the campaigns recipe. If there is no campaign, or <c> is not among
    them, stop and report which.
 3. Run <recipes>, with root = <c>, and view every id this brief names.
+   Eyes and Imagination also run `huginn known <the question in plain words>`
+   (research and ideas of every campaign, closed ones shown with their status)
+   before searching or probing. Eyes admits `research` and no other kind.
 Admit as faculty <Faculty>, agent <your name>, session <session>. A refusal
 names the rule that refused: fix the batch and admit again. InvalidInput and
 TooLarge are the same: fix the call (or narrow it) and retry. Retrying an admit
@@ -68,7 +71,7 @@ call again, otherwise revise the batch.
 Self's own checklist; Self admits as `SelfFaculty`.
 
 ```
-Open: check the eureka-state tools are present, then whoami (the mind's
+Open: check `huginn` runs, then `huginn whoami` (the mind's
 instance document, <instance>:instance:self, already exists). Write the target
 document and commit it on the working branch. Then admit the campaign
 (slug, title, every repo a cut may touch, working_branch, target_doc = a
@@ -129,6 +132,8 @@ and probe through scripts, one call per question, output at most 150 lines.
 Wait only through `tools/wait-on.sh` (never `true`, `echo` or `sleep`), write only
 under `<scratchpad>/<agent>/`, and use `py -3` for Python.
 
+Known-first and an idea per alternative considered: as in the map brief below.
+
 Give one table, a row per persistent kind:
 - Identity: what names it. Is the namespace stated? Is the name injective? Can
   two different things collide? Is any part of it derived, and from what?
@@ -155,8 +160,20 @@ sibling Self will run beside it> so Hands can go straight to the cut with
 little reading. Map nothing further ahead (SKILL.md step 1, "Map only what is
 about to run"): later cuts are one line each in the prose map's cut sequence.
 
-Admit only cut_specs, their superseding resolutions, and questions. In the
-prose map at <path>, edit body facts and rationale. Also edit the model page
+Admit only cut_specs, their superseding resolutions, questions, and `idea`s.
+Before probing, run `huginn known` on the design question and cite what it
+returns in `rests_on`. `huginn schema idea` prints the fields: `title`, `idea`, `tradeoffs` and
+`proposed_on` are required, and the label is at most 64 bytes.
+Admit an `idea` for every real alternative you considered
+that is not an option on a question you admit (those are the question's options),
+labelled `<pass>.<label>` and `toward` the question, follow_up or cut it was made
+for (empty is legal). An alternative you reject is admitted with its Recorded
+resolution, with the reason, in the same batch; one left open stays an idea in
+force for the decider to resolve. A transferable fact about the world, not this
+cut, goes to an Eyes pass. In the prose map at <path>, edit body facts and rationale. <path> is in a worktree
+Self names, at the current head of the map's branch; never the operator's
+checkout (2026-10-13: a loot-2 pass edited an operator checkout whose map was
+three days stale, beside the operator's uncommitted work). Also edit the model page
 whenever a probe changes a row's identity, lifecycle or authority. Imagination
 wrote that page in 0b, and a model a cut contradicts is stale steering text.
 Do not commit; the root agent commits. Do not change code in any repo. Scratch probes under
@@ -166,8 +183,8 @@ output at most 150 lines. Wait only through `tools/wait-on.sh` (never `true`,
 Python. Budget 40-80 calls and about 250k context.
 
 Rehydrate (recipes: target in force, rulings in force, open questions and
-follow-ups, specs with no report, one cut's record for <cuts that constrain
-this one>).
+follow-ups, specs with no report, known, one cut's record for <cuts that
+constrain this one>).
 
 Body facts to verify (not trust):
 - <repo@SHA>
@@ -186,6 +203,13 @@ The cut_spec's fields are the spec standard. Beyond filling them:
   moving. After admitting, run `py -3 tools/context-pack.py <spec id> <worktree
   at base>`: every anchor must read SAME and each window must show what its
   change names, or admit a revision.
+- code Hands must see but not change goes in `reads` (path and line range at
+  base, at most 100 lines, a `why` of at most 200 bytes, at most 16 per spec),
+  never as prose path:line in first, adds, keeps_moves or a change, unless it
+  is in another repo. Give a `symbol` on a read or file_change whose lines
+  define or call a named thing, written as it appears there. After admitting,
+  the tool at base must show every anchor SAME (or NEW, for a path the cut creates) with no SYMBOL_MISSING, or admit
+  a revision.
 - cite in `rulings` every ruling in force the cut rests on
 - the deploy owner: for any cut that changes what a service needs (transport,
   env, dependency, state), the recipe, binding and runbook that must admit it,
@@ -200,7 +224,9 @@ step 3>, admit its first part as the spec, with its own verification, and add th
 rest to the prose map's cut sequence.
 
 Where only the operator can decide, admit a question with a recommended
-option, raised in the spec it blocks.
+option, raised in the spec it blocks. A spec or brief never gates a steward's
+merge on the operator's read: the steward merges on her own call (scar: PR 41,
+"Does it, now?").
 
 Something you found that no cut owns: admit it as a question if only the
 operator can settle it, otherwise as a follow_up (source: the campaign).
@@ -226,8 +252,9 @@ Repo/branch: <repo> <branch> at HEAD <sha>. Check that git status is clean
 first. Pinned siblings: <repo@sha>. Do not change them.
 Before any grep or Read, expand the pack: `py -3 tools/context-pack.py <cut_spec
 id> <worktree>`. An anchor that reads NEW for a path the spec does not create,
-OUT_OF_RANGE, UNRESOLVED, or GONE outside deletes is a spec discrepancy: record
-it in deviations.
+OUT_OF_RANGE, UNRESOLVED, a MISSING read, SYMBOL_MISSING, or GONE outside
+deletes is a spec discrepancy: record it in deviations. The pack lists the
+callers of every symbol; grep beyond them only for what the pack names as cut.
 When the brief names a worktree, every tool call's path goes under it: Read,
 Edit and Write as well as the shell's working directory. An absolute path into
 the main checkout silently edits the wrong tree.
@@ -248,7 +275,12 @@ cites, read by id):
 Every rule the spec or the operator names gets a behavioural test. Measure the
 suite with <the ecosystem's mutation tool>, scoped to this cut's diff
 (`--since:<base>` or the tool's equivalent), against the final spelling of the
-code. The report's mutations (at most 64) holds every survivor and the kills
+code. For Rust the tool is `tools/cargo-mutants.sh <repo> <head> <base> [workdir]`,
+run ONCE per pass, at the end: it scopes each file's mutants to that file's tests,
+confirms every survivor on the full suite and shards over free slots. After killing
+survivors with tests, rerun only those names (`NAMES=<file of the MISSED names>`),
+never a second whole-diff sweep; a flaky test is skipped with
+`TEST_ARGS='--skip <name>'`. The report's mutations (at most 64) holds every survivor and the kills
 Soul should rerun; put the totals (generated, caught, unviable, missed) in
 verification evidence. Triage every survivor
 by name and line: killed by a new test, killed by fixing a degenerate fixture,
@@ -405,12 +437,18 @@ Commits:
 - Stage explicit paths only; never `git add -A`.
 - Never amend a commit or force-push. Self and other agents commit on the
   same branch while you work. Fix a commit with a new commit. On a rejected
-  push, `git pull --rebase`, then push.
+  push of a cut branch, `git pull --rebase`, then push. A merge pass that
+  pushes to master never rebases on a rejected push: rebase flattens the merge
+  commit and drops merge-time fixes (master broke at Aetheria 07854ed5,
+  2026-10-13). It fetches, merges `origin/master` into its verified merge,
+  re-verifies what the new upstream commits change, and pushes.
 - In Git Bash, one call: `git add <paths> && git commit -F- <<'MSG' ... MSG &&
   git push`. Never commit from PowerShell (it writes a BOM and breaks
   here-strings).
 - End each message with the attribution trailer.
-- Say in the message which commits don't build.
+- Before every push, build and run the test project the commit touches. A
+  commit that does not build is never pushed; if a local commit could not
+  build, say so in its message and make the pushed head build.
 
 Verification: <exact builds, tests, captures, negative greps>.
 - No test run of any size on Starfire: a "quick" local suite counts. Only
@@ -418,8 +456,9 @@ Verification: <exact builds, tests, captures, negative greps>.
   Python suites locally on 2026-10-12, red for Windows-only reasons).
 - Verify through `tools/stopgap/ygg-verify.sh` with `SUMMARY=<log>` (above):
   read the summary, and open the full log only at a named failing test, with
-  `grep -n -A 40`. Hand mutants go in one list to `tools/mutation-table.sh`,
-  one job for all of them.
+  `grep -n -A 40`. Rust mutants go to `tools/cargo-mutants.sh` (one job, scoped,
+  confirmed, sharded), hand mutants in one list to `tools/mutation-table.sh`; never
+  an inline `cargo mutants` command.
 - Stryker `--mutate` ranges are character offsets, not lines, into the file as
   Stryker reads it: the bytes of the checkout the job runs in. Line endings there
   follow `.gitattributes`, not the platform: CultLib's `packages/cultmath/src/**`
@@ -529,9 +568,11 @@ specifically:
   binaries or files the cut touches and the ones that name its rules. Run the
   full suite exactly once, at the end. Put that run in the same job as your
   mutation run where you can, since that job pays for the build anyway. Batch
-  probes into one job script rather than one job each. Run the mutation tool
-  in parallel (`--jobs 3`), and skip by name any test that a follow-up records
-  as flaky, so that its flakes cannot count a surviving mutant as killed.
+  probes into one job script rather than one job each. Run Rust mutants through
+  `tools/cargo-mutants.sh` (it shards; do not add `--jobs`), skipping any test a
+  follow-up records as flaky with `TEST_ARGS='--skip <name>'`; other ecosystems
+  run their tool in parallel (`--jobs 3`) and skip by name, so that a flake cannot
+  count a surviving mutant as killed.
   Dump the range once (`git diff <base>..<head> > <scratchpad>/<agent>/range.diff` plus
   `--stat`) and grep that file instead of re-running `git show` per file. Hand
   mutants go in one list to `tools/mutation-table.sh`, never one job each.
@@ -611,19 +652,36 @@ what was missing and what it would have prevented.
 Dispatch: `subagent_type: eyes`, model Sonnet.
 
 ```
-Write findings to <scratchpad>/<agent>/<name>.md and return a
-short summary. For a prior-art or literature pass, Self commits that file to
-<repo>/docs/research/<topic>.md before the fork goes to the operator (SKILL.md
-step 2, "Research is always kept"); write it to be read there. Budget at most 40 calls: transcripts by script, never whole
-reads, waits only through `tools/wait-on.sh`, writes only under
-`<scratchpad>/<agent>/`, Python as `py -3`, and fetches batched in parallel. You read the campaign's mind with query and view only, through
-the Rehydrate block (recipes: <as needed>); you never admit.
+Private: <yes: findings go to <path>, admit nothing | no>
+
+Budget at most 40 calls: transcripts by script, never whole reads, waits only
+through `tools/wait-on.sh`, writes only under `<scratchpad>/<agent>/`, Python as
+`py -3`, and fetches batched in parallel.
+
+Before searching, run `huginn known <the question in plain words>` and, for
+legacy matter, `huginn sources`. Search the world only for what those do not
+answer. Read the campaign's mind with the Rehydrate block (recipes: <as needed>).
+
+`huginn schema research` prints the fields and bounds: `claim` (1000 bytes), `detail`
+(4000), `sources` (16), and required `serves`, `detail`, `observed_on`.
+Admit what you find as `research` notes through `huginn admit` (the strict door,
+not the MCP tool), faculty Eyes: one document per claim, nothing else admitted.
+Label each `<pass>.<label>`: the local part is 64 bytes in all, so the pass is at
+most about 24 bytes and the label at most about 38. The first note is labelled
+`scope`: your method and what you did not search. Every note has a source (a repo
+pin, a web page, something you observed, or another document); `inferred: true`
+names a claim you read from its sources rather than saw in them. A note is a fact,
+never a recommendation. A batch is 1 to 64 documents; a larger pass spans batches
+under one pass label. A wrong or superseded note is not edited: admit the new one
+and leave the old to a steward. You resolve nothing. Raw output too long for a note
+stays under `<scratchpad>/<agent>/` and the note cites it as an Observed capture.
+If Private is yes, admit nothing and write to the file named. Report the pass label
+and counts, not the findings again.
 
 Sources:
 - <repos and ranges>
 - <transcripts> (grep with targeted patterns; never read whole)
 - <docs>
 
-Produce facts with evidence pointers (SHA, file:line, transcript line). Mark
-anything inferred as "(inferred)".
+Facts carry evidence pointers (SHA, file:line, transcript line).
 ```

references/campaign-state.md

@@ -4,7 +4,7 @@ A campaign keeps its state in two places, and nothing lives in both.
 
 - **The mind.** Questions, rulings, cut specs, reports, verdicts, findings,
   follow-ups and resolutions are typed documents in the instance's mind, held by
-  Huginn and reached through the `eureka-state` MCP tools. Status is derived
+  Huginn and reached through the `huginn` CLI. Status is derived
   from them on every read; nobody writes it.
 - **The prose.** A target document and a map document, committed in the repo
   the campaign changes. They keep only what no kind carries: body facts (probes
@@ -15,17 +15,20 @@ The shapes below are the leaf's (`epiphany-pipeline`, pinned by Huginn) and the
 organ's (`huginn-mind`). Where this page and the tools' own schemas disagree,
 the tools are right and this page is stale.
 
-## The tools
+## The CLI
 
-The instance and the daemon are the server's configuration
-(`EUREKA_INSTANCE`, `HUGINN_ENDPOINT`), never an argument.
+The instance and the daemon are the environment (`EUREKA_INSTANCE`,
+`HUGINN_ENDPOINT`), never an argument. The table names each tool's input and
+answer; the CLI form is in the first column. `huginn --help` and
+`huginn schema [kind]` are the source. A client without a shell may use the
+`eureka-state` MCP, whose tools these are, until a native `huginn` is installed.
 
-| Tool | Input | Answer |
+| CLI | Input | Answer |
 |---|---|---|
-| `whoami` | `{}` | `{ instance, endpoint, reachable, status }`. `status` is `{ instance, schema_epoch, documents, receipts, index }`, and `index` is `Current`, `Reconciling`, `Behind`, `Failing` or `Refused`. When unreachable, `error` says why. |
-| `admit` | `{ faculty, agent, session, documents }` | `Committed { receipt_id, committed_at, writes }`, `AlreadyAdmitted { receipt_id }`, `Conflict { identities }` or `Refused(<refusal>)`. One to 64 documents, admitted whole or not at all. |
-| `view` | `{ id: { kind, id } }` | `{ id, document, admission, status }`, or `null`. |
-| `query` | `{ selection, semantic? }` | `{ matched, as_of, next, items, edges }`. `items` is `Headers([...])` or `Documents([...])`. |
+| `huginn whoami` | none | `{ instance, endpoint, reachable, status }`. `status` is `{ instance, schema_epoch, documents, receipts, index }`, and `index` is `Current`, `Reconciling`, `Behind`, `Failing` or `Refused`. When unreachable, `error` says why. |
+| `huginn admit --faculty F --agent A --session S <file or ->` | a JSON array of 1 to 64 `{kind, value}` documents (file or stdin) | `Committed { receipt_id, committed_at, writes }`, `AlreadyAdmitted { receipt_id }`, `Conflict { identities }` or `Refused(<refusal>)`. One to 64 documents, admitted whole or not at all. |
+| `huginn view <root:kind:local> [--raw]` | the document id | `{ id, document, admission, status }`, or `null`. |
+| `huginn query '<selection json>' [--near TEXT --top-k N] [--documents]` (or `@file`, or `-`) | the selection alone; `--near` is `semantic` | `{ matched, as_of, next, items, edges }`. `items` is `Headers([...])` or `Documents([...])`. |
 
 - `faculty` is one of `SelfFaculty`, `Imagination`, `Hands`, `Soul`,
   `Life`, `Eyes`, `Operator`. It is attribution, not authority.
@@ -51,9 +54,8 @@ The instance and the daemon are the server's configuration
 
 This is the one rule for every faculty.
 
-1. **The tools are missing** from the session's tool surface: stop and tell the
-   operator (a subagent tells Self). A server registered after the session
-   started appears only in a new session. Never fall back to prose.
+1. **`huginn` does not run** in the session's shell: stop and tell the
+   operator (a subagent tells Self). Never fall back to prose.
 2. **`Unavailable`:** retry the same call once. A cold semantic embed after an
    idle spell took over 15 s live, which is the client's whole timeout.
    Retrying `admit` is safe, because an exact replay answers `AlreadyAdmitted`.
@@ -76,20 +78,22 @@ mismatch. The root is the campaign slug, or the instance for `instance`,
 |---|---|---|---|---|
 | `instance` | `self` | exists (`eureka:instance:self`) | instance, display name, host | |
 | `stewardship` | `<repo>.n<seq>` | Self | instance, repo, sequence, note | |
-| `campaign` | `self` | Self | title, repos, working branch, target doc | |
-| `target` | `r<rev>` | Self | invariants (`label`, `statement`), not in scope, canonical implementations, doc | |
+| `campaign` | `self` | Self | title, repos (the opening set), working branch, target doc | |
+| `target` | `r<rev>` | Self | invariants (`label`, `statement`), not in scope, canonical implementations, doc, repos (the whole set from this revision on; empty keeps the previous) | |
 | `question` | `<label>` | Imagination; Hands or Soul for a fork | title, question, options (≥2), recommended, depends, raised in | `raised_in` |
 | `ruling` | `<label>` | Self | answers (none for an operator direction), choice, ruling, operator quote, date, authority | `answers` |
-| `cut_spec` | `cut-<cut>.r<rev>` | Imagination | repo, branch, base, depends on (cut labels, never revision ids; a spec may not depend on its own cut), first, deletes, keeps and moves, adds, file changes, authority map, verification, estimate | `rulings`, `questions` |
+| `cut_spec` | `cut-<cut>.r<rev>` | Imagination | repo, branch, base, depends on (cut labels, never revision ids; a spec may not depend on its own cut), first, deletes, keeps and moves, adds, file changes, reads (each a location and why; any location may carry a symbol), authority map, verification, estimate | `rulings`, `questions` |
 | `cut_report` | `cut-<cut>.h<attempt>` (a fix batch is the next attempt) | Hands | commits, range, verification evidence (mutation totals included), mutations (survivors and the ones Soul should rerun), deviations, forks, structural delta, landed names, undone, promises | `cut_spec`, `forks` |
 | `verdict` | `cut-<cut>.s<pass>` | Soul | range, claims (each with an outcome, evidence, findings, promise, mutations) | `cut_report`, `findings` |
 | `finding` | `cut-<cut>.s<pass>.<label>` | Soul, in the verdict's batch | confidence, severity, claim, invariants, locations, failure scenario, evidence, origin | `verdict` |
 | `follow_up` | `<label>` | Self; Imagination for work no cut owns | source, repo, locations, item, why it can wait, owner | `source` |
+| `research` | `<pass>.<label>` | Eyes | pass, label, claim, detail, inferred, sources (repo pin, web page, observed, document), serves, observed on; the pass's first note is `scope` | `serves`, document sources |
+| `idea` | `<pass>.<label>` | Imagination | pass, label, title, idea, tradeoffs, rests on, toward, proposed on | `rests_on`, `toward` |
 | `resolution` | `<subject kind>.<subject local>.n<seq>` | whoever closes the subject | subject, sequence, outcome, rationale, date | `subject`, and the outcome's referents |
 | `hand_off` | `<to>.<repo>.<date>` | Self (parked: Cut 12) | from, to, repo, documents, reason | `documents` |
 
 Bounds: `Title` and `Short` are at most 200 bytes, `Line` 1,000, and `Para`
-4,000. Narrative longer than that goes in the prose map, cited by a `DocRef`
+4,000. A target's `repos` is at most 16, a campaign's 8. Narrative longer than that goes in the prose map, cited by a `DocRef`
 (path, start and end line, commit). A `Label` is `[A-Za-z0-9_-]{1,64}`, and a
 `Date` is `YYYY-MM-DD`. A subject's local key (the part after
 `<campaign>:<kind>:`) is at most 64 bytes. A resolution's local is derived from
@@ -98,7 +102,13 @@ resolved and withdrawn.
 
 Rules that shape a batch (the rest arrive as refusals):
 
-- A cut spec's repo must be one of its campaign's repos.
+- A cut spec's repo must be in the repo set in force when the spec is admitted:
+  the target in force's `repos` when it names any, else the campaign's. Specs
+  already in force on a since-removed repo stay in force and can still be
+  reported, withdrawn or superseded; a new revision of one is refused. Self adds
+  or removes a repo with target `r<n+1>` naming the whole set, plus the
+  superseding resolution. A target revision may not empty a `repos` list its
+  predecessor named (`EmptyRepos`).
 - A ruling that `answers` a question derives that question's `Answered`
   resolution in the same commit. Its `choice` must be one of the question's
   option labels. `operator_quote` is allowed only with `authority: Operator`.
@@ -192,7 +202,7 @@ or `view` one id, to read the prose fields.
 ## Recipes
 
 These are the campaign's progress view. `<c>` is the campaign slug. Each recipe is
-the `query` tool's whole input. Agents run them from the Rehydrate block in
+the `selection` value of `huginn query`; the CLI takes the object inside the `selection` key, and `--near`/`--top-k` replace `semantic`. Named verbs (`huginn campaigns`, `rulings`, `open`, `findings`, `unreported`, `unjudged`, `cut`, `precedent`) run the common recipes. Agents run them from the Rehydrate block in
 `briefs.md`, which is the one definition of rehydration.
 
 **Campaigns:**
@@ -206,6 +216,10 @@ the `query` tool's whole input. Agents run them from the Rehydrate block in
 - **`<c>` is not in the list:** the slug is wrong or the campaign is in another
   mind. Stop and report; never create a campaign to fit a brief.
 
+**Repos in force:** `huginn target <c>`. Its `repos` when non-empty, else the
+campaign's `repos` (`huginn campaigns`, the opening set). A cut spec's repo must be
+in this set.
+
 **Target in force:** `target`, with `root` = `<c>`, `in_force` = `true` and
 `projection: document`.
 
@@ -286,6 +300,14 @@ reading its verdicts and findings, check that `admission.provenance.faculty` is
 `ruling`, `resolution` and `finding` with `root` = `<c>`, plus
 `"semantic": { "text": "<the question in plain words>", "top_k": 10 }`.
 
+**Research and ideas:** `huginn known <text>` finds the nearest notes and ideas
+in every campaign, closed ones included, with their status; `huginn pass
+<campaign> <pass>` lists one pass whole; `huginn ideas <campaign>` lists the
+ideas in force. Known is cross-campaign and shows closed notes; precedent is
+rulings, resolutions and findings. Neither a note nor an idea stores a status:
+its resolutions say what became of it. `huginn schema research|idea` prints the
+shape.
+
 Once the operator installs the hook, `tools/recall.py` also puts the nearest in-force
 rulings, questions and follow-ups into every prompt; the recipe remains the
 deliberate check before raising a question.
@@ -348,6 +370,11 @@ invariants, not-in-scope list and canonical implementations are the typed
 - **Admit only the ruling that answers a question.** Its `Answered`
   resolution is derived in the same commit; admitting that resolution by hand
   is refused `IdentityCollision`.
+- **Re-mapping a withdrawn cut takes two batches.** First admit a `Withdrawn`
+  resolution on the spec's withdrawal resolution, which reopens the spec. Then,
+  in a second batch, admit revision N+1 with a `Superseded` resolution on
+  revision N. One batch holding both is refused `WouldReinstateOverLater`
+  (loot-2 r3, 2026-10-13). A fresh cut label at revision 1 needs neither.
 - **A finding cannot be resolved `Superseded`** (`IncompatibleResolution`).
   Resolve it `Recorded`, naming its successor in the reason.
 - **Test negative greps before publishing them** in a spec's
@@ -358,3 +385,10 @@ invariants, not-in-scope list and canonical implementations are the typed
 - **Prefer normalizers that parse the format.** Ones that split on text leave
   false diffs, as the census normalizer did when it split on `, ` and glued the
   first maker to its kind column.
+
+## Known CLI gap
+
+The `eureka-state` MCP also offers `persona_get` and `persona_put`. The `huginn`
+CLI has no persona verb (`huginn --help` lists none). Persona state stays on the
+MCP until Huginn grows one; this is a Huginn follow-up, not something to fake
+with `admit`.

references/changelog.md

@@ -2,6 +2,32 @@
 
 Record each change to the skill together with the evidence that motivated it.
 
+## 2026-11-05: Eyes and Imagination keep their findings as typed notes
+
+Self, session `self-2026-11-04-eureka`; cut `eureka-body:cut_spec:cut-typed-research-skill.r1`.
+
+Evidence. Rulings `eureka-body:ruling:research-and-ideas-are-typed-documents` (operator: "Imagination and eyes should both return their findings in typed documents so we never lose any research or ideas"), `research-public-face-ruled` (the mind owns research; existing files stay; a generated projection is wanted) and `private-pass-home-ruled`; kinds and verbs from `cut-typed-research` h3 and s2 (release 809a93c answers `huginn known|pass|ideas`).
+
+What changed. Eyes admits `research` (one note per claim, a source on each) and Imagination admits `idea`s besides its questions, cut_specs and follow_ups, both through `huginn admit` after reading `huginn known`. Self reads `known` before dispatching a pass and a question cites the notes it stands on in `raised_in`. The old path is removed: the Eyes facts file that admitted nothing, Self committing a prior-art file to `docs/research/` before the fork, and the Eyes `you never admit`. Committed `docs/research/` files stay untouched, read through `huginn sources`; the renderer that projects a public pass to `docs/research/` is not built, so a public pass lives in the mind only. A private pass admits nothing and returns to the file its brief names. `references/campaign-state.md` gains the `research` and `idea` rows and the `known`, `pass` and `ideas` recipes; the Eyes and Imagination charters gain the matching boundaries. No `tools/` change.
+
+The crossing. Huginn client 809a93c; the first `research` and `idea` documents were admitted at 2026-11-05T10:24Z: receipts `mind-commit-8f5dd1a6f6860a6052a9797aa79bf336946c7b59e0e7fdc8d1228c3b9a88f826` (research `skill-cut-map.scope` and `.old-path`) and `mind-commit-fcae00c87ef2b2a74c9f09f0485a7e1ada6207dc749dcec12758a40c050b7030` (idea `skill-cut-map.backfill-old-research`). Huginn does not roll back by flipping `current` from here.
+
+## 2026-11-02: inversion of control, originator evidence, persona charter once
+
+Self, session `self-2026-11-02-eureka`.
+
+Evidence. Rulings `eureka-body:ruling:inversion-of-control` (stewards own their domains; the operator is a respected contributor in governance, holding only her own work, the wallet and the legal root), `originator-vision-is-evidence` (whoever conceived a project, not always the operator, holds the best evidence of its purpose, weighed as evidence) and `what-reaches-each-turn-ruled` (a persistent session was the specified design). A brief gated a steward's merge on the operator's read (PR 41, "Does it, now?").
+
+What changed. `SKILL.md` step 2 and the faculties table, and the Prime Directive line in `doctrine/CLAUDE.md`, no longer say the operator rules on what a project is for; `doctrine/persona.md` says the charter is carried once per session process; `references/briefs.md` says a spec or brief never gates a steward's merge.
+
+## 2026-10-27: re-entry triage, second-beating trigger, pushed heads build
+
+Self, sessions `self-2026-10-27-eureka` and `self-2026-10-27b-eureka`.
+
+Evidence. A recovery Soul pass found High defects in two cuts whose reports had sat days with no verdict (Bifrost OIDC stale client, Heimdall boot-proof pin); re-entry rehydration did not list reports with no verdict. The "same rule beaten again" step fired twice in one session (boot-proof verdict owner; the C2a claimant rule beaten on claimant, compatible ids and shape) and both times only a structural move fixed it; the step's text read as a mutant-only, late trigger. Hands pushed a non-building commit in four consecutive batches although the brief said "Say in the message which commits don't build", which permits it.
+
+What changed. `SKILL.md` re-entry adds reports with no verdict and an origin check before trusting a handoff's status words; step 5 says the trigger is the second beating, by mutants or findings. `references/briefs.md` Hands commit rules: build and run the touched test project before every push; pushed heads build.
+
 ## 2026-10-23: worktrees die with their cut
 
 Self, session `self-2026-10-23-ag8`.
@@ -9,6 +35,13 @@ Self, session `self-2026-10-23-ag8`.
 Evidence. `C:\aeth-wt` held 255 GB, mostly 1.7-3.9 GB Unity worktrees from sessions ag3 to ag7. The ag7 handoff listed them as "worktrees to remove when idle". C: was at 1.4 GB free while the operator flew, and a new worktree checkout failed mid-write. A two-pass sweep removed about 140 worktrees and directories. Operator: "you really gotta start cleaning up after yourself".
 
 What changed. `SKILL.md` git and tooling rules: Self removes a cut's worktrees in the turn the cut merges or is abandoned, parks unreferenced heads under `keep/` tags first, and checks free space before creating a worktree.
+## 2026-10-14: one feature across two areas
+
+Self, session `self-2026-10-14-ag`.
+
+Evidence. Fauna's trophic placement (aetheria-fauna, Aetheria area) needed the CultMath tape and nodes (cultmath-tapes, Eureka area). The operator ruled tape and node questions in the Aetheria session; the Aetheria Self admitted her rulings there and messaged the Eureka Self with ids, which mapped and ran the CultMath cuts and messaged spec ids back. Nothing in the skill said how two Selves coordinate (Life, 2026-10-14).
+
+What changed. `SKILL.md`, the area paragraph: the Self that hears the operator admits her ruling; work goes to the owning area's Self by message with ids.
 
 ## 2026-10-14: nothing that exists is sacred, her words included
 
@@ -25,6 +58,15 @@ Evidence. `aetheria-release:cut_report:cut-sensor-catalog.h4` names branch `eure
 
 What changed. `SKILL.md`, Self's worktree bullet: the worktree's branch is the spec's `branch` field, spelled exactly.
 
+## 2026-10-13: a merge pass never rebases on a rejected push
+
+Self, session `self-2026-10-13-ag`.
+
+Evidence. `aetheria-release:cut_report:cut-reveals-replace-tiers.h3`: the merge agent's first push to master was rejected because a docs commit had landed. Following the Hands brief ("On a rejected push, `git pull --rebase`, then push"), it rebased: that flattened the merge commit and dropped its merge-time fix to two test files, so Aetheria master 07854ed5 did not compile until the agent repaired it forward in 20cd1d7c. Master history now carries the cut's commits twice.
+
+What changed. The Hands brief's commit rules keep `git pull --rebase` for cut branches only. A merge pass that pushes to master fetches, merges `origin/master` into its verified merge, re-verifies what the new upstream commits change, and pushes.
+
+
 ## 2026-10-12: no test run of any size on Starfire
 
 Self, session `self-2026-10-12-eureka`.

tools/INDEX.md

@@ -11,8 +11,10 @@ gets a Soul pass before merge.
 | `tools/stopgap/ygg-verify.sh` | Pushes an exact revision to a mirror on Yggdrasil and runs one command in a capped, niced container (`RUN_ON_HOST=1`: run a host-side command in the same slot, clone and watchdog instead; the watchdog kills every container carrying the job label). `SUMMARY=<log>` keeps the full log and prints a bounded summary (verdict, counts, ZERO TESTS RAN, failing tests); `wait <log>` blocks at most 270 s and returns the summary once; call it with a Bash tool `timeout` of at least 280000 ms. Dies with the stopgap when Idunn's verify transaction lands. | Hands, Soul, Imagination probes | `references/briefs.md` (Hands long jobs and verification, Soul long jobs), `SKILL.md` (Yggdrasil) |
 | `tools/wait-on.sh` | One general waiter for anything that is not a Yggdrasil job: `pid <pid> [<log>]`, `log <log> <done-regex>` (with `WAIT_PID=<pid>` a dead process with no match is exit 98; an invalid ERE is exit 3), `file <path>`. The `pid` form prints `GONE (no completion evidence)`: prefer `log` whenever the job writes a done line. Same contract as `ygg-verify.sh wait`: blocks at most 270 s, exit 0 done with a tail of at most 60 log lines, `RUNNING <n>s` exit 99, exit 98 gone with no completion evidence; call it with a Bash tool `timeout` of at least 280000 ms. Replaces hand-rolled poll loops and idle `true`/`echo`/`sleep` calls. | Hands, Soul, Imagination probes | `references/briefs.md` (Hands long jobs, Soul long jobs, detached scripts) |
 | `tools/mutation-table.sh` | One verify job that runs a list of hand mutants (file, before, after, test) against a revision and returns a kill table: CAUGHT with the killing test, SURVIVED, UNVIABLE, TIMEOUT, NOAPPLY, ERROR. Refuses a red or zero-test baseline and a red BUILD; rows print live. Isolation is Docker's: the baselines run once in a container that holds the revision, that container is committed to a throwaway image, and every mutant runs in a fresh `--rm` container from it, so nothing a run writes (tracked, untracked or ignored, such as `target/`) reaches the next mutant; the image is removed when the job ends, killed or not. The shared registry and sccache volumes and the network are not isolated. A file-level load failure (vitest `FAIL <file> [ <file> ]`, jest `FAIL <file>` plus `Test suite failed to run`) reads UNVIABLE. Replaces per-agent runmut/mutrun/strykrun scripts. | Soul, Hands (scoped run) | `references/briefs.md` (Hands verification, Soul reruns) |
-| `tools/testparse.sh` | Sourced library: failing test names and pass/fail/skip counts from cargo, dotnet, vitest, jest and pytest logs, and test files that failed to load (`LOADFAIL`). Shared by the summary and the kill table. | the two scripts above | not named by a brief; it lives and dies with them |
-| `tools/test-tools.sh` | Local fixture check of the parsers and the summary over `tools/fixtures/logs` (real cargo and mutation logs, plus hand-written dotnet, vitest, jest, pytest, exit-0-but-failed and no-verdict logs), and of the mutation runner's host driver and container half under a mock docker. Run it before merging a change to the scripts above. | whoever changes those scripts | `SKILL.md` (Shared tools) |
-| `tools/context-pack.py` | `py -3 tools/context-pack.py <cut_spec id> <worktree> [--since <sha>] [--only <k>[,<k>...]] [--spec-json <file>] [--max-lines <n>]`. Carries a cut_spec's `file_changes` anchors from the spec's base to the worktree by `git diff` hunks (the working tree included) and prints one header, a status table (SAME, MOVED, TOUCHED, RENAMED, NEW, GONE, OUT_OF_RANGE, UNRESOLVED) and windows of at most 100 lines numbered in worktree lines, within `--max-lines` (800). Exit 3 when an anchor cannot be carried, 4 when the spec is unreadable (fetched by id through the eureka-state binding (`tools/mind.py`), retried once on Unavailable; `--spec-json` takes a saved view). `--since <sha>` re-prints only the windows edited since that commit. Standard library plus git; writes nothing. | Hands, Soul, Imagination | `references/briefs.md` (Imagination map, Hands, Soul), `SKILL.md` (step 1) |
+| `tools/cargo-mutants.sh` | `SUMMARY=<log> tools/cargo-mutants.sh <repo> <rev> <base> [workdir]`: cargo-mutants on a revision range as ONE verify job, the one owner of running it. Plan container lists the range's mutants (diff taken at the workspace root); stage 1 runs each file's mutants against that file's tests only (filter derived from the path, `FILTERS` overrides), deciding only CAUGHT and UNVIABLE; stage 2 confirms every survivor, timeout, unfiltered file and zero-test file on the full suite, sharded; merge counts each name once and prints `MUTANTS` totals, `FILTER` lines and the final `MISSED`/`TIMEOUT` names. Containers = min(`SHARDS`, slots, units, 1 + free slots), leased with `flock -n` from Yggdrasil's slot pool (none while IO pressure full avg60 > 20). `NAMES=<file>` reruns chosen survivors (no stage 1), `TEST_ARGS` skips flaky tests, `JOBS`, `MIN_TEST_TIMEOUT`, `CONFIRM_TIMEOUT_MULT`, `TIMEOUT`. Exit 0 on a green baseline whatever survives; a red baseline or a failed container is non-zero with no totals. Run once per pass. | Hands, Soul | `references/briefs.md` (Hands verification, Soul reruns), `SKILL.md` (mutation bullet) |
+| `tools/testparse.sh` | Sourced library: failing test names and pass/fail/skip counts from cargo, dotnet, vitest, jest and pytest logs, and test files that failed to load (`LOADFAIL`). Shared by the summary and the kill table. | `tools/stopgap/ygg-verify.sh`, `tools/mutation-table.sh` | not named by a brief; it lives and dies with them |
+| `tools/test-tools.sh` | Local fixture check of the parsers and the summary over `tools/fixtures/logs` (real cargo and mutation logs, plus hand-written dotnet, vitest, jest, pytest, exit-0-but-failed and no-verdict logs), and of the mutation runners' host drivers and container halves (`tools/mutation-table.sh`, `tools/cargo-mutants.sh`) under a mock docker, a fake `cargo mutants` and real slot locks. Run it before merging a change to the scripts above. | whoever changes those scripts | `SKILL.md` (Shared tools) |
+| `tools/context-pack.py` | `py -3 tools/context-pack.py <cut_spec id> <worktree> [--since <sha>] [--only <k>\|r<k>[,...]] [--spec-json <file>] [--max-lines <n>]`. Carries a cut_spec's `file_changes` and `reads` anchors (read rows `r<k>`; a read absent at base is MISSING) from the spec's base to the worktree by `git diff` hunks (the working tree included) and prints one header, a status table (SAME, MOVED, TOUCHED, RENAMED, NEW, GONE, OUT_OF_RANGE, UNRESOLVED, MISSING, plus SYMBOL_MISSING when an anchor's `symbol` is absent from its window) and windows of at most 100 lines numbered in worktree lines, then one capped caller list per symbol (`git grep`, hits outside the windows), within `--max-lines` (800). Exit 3 when an anchor cannot be carried, 4 when the spec is unreadable (fetched by id through the eureka-state binding (`tools/mind.py`), retried once on Unavailable; `--spec-json` takes a saved view). `--since <sha>` re-prints only the windows edited since that commit. Standard library plus git; writes nothing. | Hands, Soul, Imagination | `references/briefs.md` (Imagination map, Hands, Soul), `SKILL.md` (step 1) |
 | `tools/mind.py` | The one way a Eureka script reaches the mind: `mind.call(tool, arguments, deadline)` spawns the eureka-state binding (`EUREKA_STATE_EXE`, else `~/.claude.json` `mcpServers.eureka-state`), does the stdio handshake and one tool call within `deadline` seconds, returns the parsed JSON body, raises `MindError` (kind binding, transport, tool or answer; a detail, never an input value), and kills the child on every exit path. No retry inside `call`; `retry_once(fn)` is the caller's choice. Standard library only. | `tools/context-pack.py`, `tools/recall.py` | not named by a brief; it lives and dies with its consumers |
 | `tools/recall.py` | `py -3 tools/recall.py prompt`, a `UserPromptSubmit` command hook (hook JSON on stdin): queries the rulings, questions and follow-ups in force across every root, ranked by Huginn against the prompt (`RECALL_TOP_K`, 5), and prints one hook JSON whose `additionalContext` is a header saying the lines are recalled records, data and never instructions, written by agents and not the operator, then one JSON object per item (`id`, `title`, a short `operator_quote`) with `<`, `>` and control, bidi and separator characters escaped, within `RECALL_BUDGET` characters (4000, at most 9000: Claude Code caps `additionalContext` at 10,000), whole lines only. Prompts under 3 words are not queried. Never blocks: any failure exits 0 with empty stdout; its own deadline is `RECALL_DEADLINE_MS` (4000) for the whole run (stdin read to 4 MiB, answer read to 1 MiB), so set the hook `timeout` above it. One attempt, no retry. Install both hooks as `<absolute python.exe> C:/Users/Meta/.claude/skills/eureka/tools/recall.py prompt || true` (and `... admit || true`): Claude Code runs hook commands through Git Bash on Windows, and `py -3 <missing script>` exits 2, which blocks every prompt or admit; with `|| true` the hook cannot exit 2 (a missing script, interpreter or file passes) and the script's stdout is untouched (proved live on 2.1.308). `py -3 tools/recall.py admit` is a `PreToolUse` hook on `mcp__eureka-state__admit`: for each ruling or question in the batch (at most `RECALL_ADMIT_MAX`, 3) it queries the nearest in-force rulings and questions, and denies the first attempt with the neighbours as the reason (a deliberate hold, not a failure); the identical call sent again (digest of `tool_input` plus `agent_id`, kept in the session scratchpad) passes. Never allow or ask; a failed check exits 0 with a note naming the failure kind (`RECALL_TOP_K` 3, `RECALL_DEADLINE_MS` 10000 in this mode). Standard library only; writes only the digest file. | the operator's `UserPromptSubmit` hook and `PreToolUse` hook on `mcp__eureka-state__admit` (fires inside subagents too) in `~/.claude/settings.json` | `references/campaign-state.md` (Precedent) |
+| `tools/bloom-sheet/bloom_sheet.py` | `bloom-sheet notes.md -o sheet.png [--visitor a.svg]...`: a markdown document as one neon A4 page. The first top-level heading is the title, every other heading a card sized by its text; a plant grows through what's left, and each SVG visitor gets a disc it grows around and is drawn with the plant's pen, so it must be flat strokes or fills that touch; large fills become a wash and a heavy outline. PDF or PNG, about 2.5 minutes. `grow.py` owns the plant, `page.tex` the look, `test_visitors.py` what a visitor may be. | Minds and Self, for info renders | the `bloom-sheet` skill; `bloom-sheet` on Yggdrasil's PATH |

tools/bloom-sheet/bloom_sheet.py

@@ -0,0 +1,441 @@
+#!/usr/bin/env python3
+"""Turn a markdown document into a one-page neon bloom sheet.
+
+  bloom_sheet.py notes.md -o sheet.png
+
+The first top-level heading is the page title and the paragraph right after it
+the subtitle; every other heading becomes a card, sized by how much it holds.
+The plant grows through whatever the cards leave, and --visitor perches your
+SVGs in the garden. Output is PDF or PNG, by the extension of -o. Takes about
+two minutes: the growth, then LuaLaTeX twice.
+
+A visitor is drawn with the plant's own pen, not pasted in. Stroked shapes
+become weighted neon lines, and a fill under a stroke becomes a faint wash, as
+on a petal. A shape with only a fill is drawn the same way with a heavy line,
+unless it is small: spots and eyes stay solid, like a flower's centre. Colours
+snap to the sheet's palette, near-black paints the ground (a cutout), and
+opacity is ignored. All of it must touch, reading as one thing; a closed
+outline counts as covering its inside. Text, images and gradients are refused.
+
+Needs python3-numpy, python3-markdown-it, LuaLaTeX with tikz and tcolorbox,
+pdftoppm for PNG, the Ubuntu, IBM Plex Mono and Montserrat fonts, and for
+visitors python3-svgelements and python3-shapely.
+Everything from the document is escaped, and LaTeX runs with no shell escape.
+"""
+import argparse, colorsys, json, math, os, random, re, shutil, subprocess, sys, tempfile, zlib
+from pathlib import Path
+
+from markdown_it import MarkdownIt
+
+HERE = Path(__file__).resolve().parent
+W, H = 210.0, 297.0
+MARGIN, GUTTER = 5.0, 7.0
+TITLE_H = 21.2
+COLOURS = ["neonorange", "neonsky", "neonviolet"]
+# Files first, then family names: a font's packaging differs between machines.
+FONTS = r"""
+\IfFontExistsTF{Ubuntu-L.ttf}{%
+  \setmainfont{Ubuntu-L.ttf}[BoldFont=Ubuntu-B.ttf]
+  \newfontfamily\speakfont{Ubuntu-R.ttf}[BoldFont=Ubuntu-B.ttf]
+}{%
+  \setmainfont{Ubuntu}[UprightFont=* Light, BoldFont=* Bold]
+  \newfontfamily\speakfont{Ubuntu}[BoldFont=* Bold]
+}
+\IfFontExistsTF{IBMPlexMono-Regular.otf}{%
+  \newfontfamily\numfont{IBMPlexMono-Regular.otf}
+  \newfontfamily\labelfont{IBMPlexMono-Medium.otf}[LetterSpace=14]
+}{%
+  \newfontfamily\numfont{IBM Plex Mono}
+  \newfontfamily\labelfont{IBM Plex Mono}[UprightFont=* Medium, LetterSpace=14]
+}
+\IfFontExistsTF{Montserrat-Thin.ttf}{\newfontfamily\thinfont{Montserrat-Thin.ttf}}{\newfontfamily\thinfont{Montserrat}[UprightFont=* Thin]}
+"""
+
+TEX_SPECIAL = {"\\": r"\textbackslash{}", "{": r"\{", "}": r"\}", "$": r"\$", "&": r"\&", "#": r"\#",
+               "%": r"\%", "_": r"\_", "^": r"\textasciicircum{}", "~": r"\textasciitilde{}"}
+
+
+def esc(text):
+    return "".join(TEX_SPECIAL.get(c, c) for c in text)
+
+
+def esc_code(text):
+    """Escaped, with break points: code and URLs have no spaces to wrap at."""
+    return re.sub(r"(/|\.)", r"\1\\allowbreak{}", esc(text))
+
+
+def inline(token):
+    """Render one inline token's children as LaTeX; returns (tex, plain text)."""
+    tex, plain, stack = [], [], []
+    link = None
+    for t in token.children or []:
+        if t.type == "text":
+            tex.append(esc(t.content)); plain.append(t.content)
+        elif t.type == "code_inline":
+            tex.append(r"\code{" + esc_code(t.content) + "}"); plain.append(t.content)
+        elif t.type in ("softbreak", "hardbreak"):
+            tex.append(" " if t.type == "softbreak" else r"\newline{}"); plain.append(" ")
+        elif t.type in ("strong_open", "em_open"):
+            tex.append(r"\strong{" if t.type == "strong_open" else r"\soft{")
+        elif t.type in ("strong_close", "em_close"):
+            tex.append("}")
+        elif t.type == "link_open":
+            link = (t.attrGet("href") or "", len(plain))
+        elif t.type == "link_close" and link:
+            href, start = link
+            if href and href != "".join(plain[start:]):
+                tex.append(r" \faint{" + esc_code(href) + "}")
+            link = None
+        elif t.type == "image":
+            alt = t.content or "image"
+            tex.append(r"\faint{[" + esc(alt) + "]}"); plain.append(alt)
+    return "".join(tex), "".join(plain)
+
+
+class Card:
+    def __init__(self, head=None, level=7):
+        self.head, self.level, self.parts, self.chars = head, level, [], len(head or "")
+
+    def add(self, tex, chars):
+        self.parts.append(tex)
+        self.chars += chars + 30     # each block costs a line's start and some space
+
+    def tex(self):
+        return (r"\head{" + esc(self.head) + "}\n" if self.head else "") + "\n".join(self.parts)
+
+
+def table(tokens, i):
+    """A pipe table as a tabular of equal ragged columns. Returns (tex, chars, next i)."""
+    rows, row, is_head = [], [], False
+    while tokens[i].type != "table_close":
+        t = tokens[i]
+        if t.type == "tr_open": row = []
+        elif t.type == "th_open": is_head = True
+        elif t.type == "td_open": is_head = False
+        elif t.type == "inline":
+            tex, plain = inline(t)
+            row.append((r"\strong{" + tex + "}" if is_head else tex, plain))
+        elif t.type == "tr_close": rows.append(row)
+        i += 1
+    n = max(len(r) for r in rows)
+    col = r">{\cell}p{\dimexpr(\linewidth - %d\tabcolsep)/%d\relax}" % (2 * (n - 1), n)
+    body = " \\\\\n".join(" & ".join(c[0] for c in r + [("", "")] * (n - len(r))) for r in rows)
+    chars = sum(max(len(c[1]) for c in r) * n + 10 for r in rows)
+    return r"\par\begin{tabular}{@{}" + "".join([col] * n) + "@{}}\n" + body + " \\\\\n\\end{tabular}\\par", chars, i
+
+
+def parse(text, card_level):
+    """Returns (title, subtitle, cards)."""
+    tokens = MarkdownIt("commonmark").enable("table").enable("strikethrough").parse(text)
+    title, subtitle, cards = None, None, []
+    card = None
+    depth, ordered, quote = 0, [], 0
+    i = 0
+    while i < len(tokens):
+        t = tokens[i]
+        if t.type == "heading_open":
+            level = int(t.tag[1])
+            _, plain = inline(tokens[i + 1])
+            if level == 1 and title is None and not cards and card is None:
+                title = plain
+                nxt = tokens[i + 3] if i + 3 < len(tokens) else None
+                if nxt is not None and nxt.type == "paragraph_open":
+                    subtitle = inline(tokens[i + 4])[1]
+                    i += 3
+            elif level <= card_level:
+                # a heading with nothing of its own is its first child's section name
+                if card is not None and card.head and not card.parts and level > card.level:
+                    plain = f"{card.head} · {plain}"
+                    cards.pop()
+                card = Card(plain, level); cards.append(card)
+            else:
+                if card is None:
+                    card = Card(); cards.append(card)
+                card.add(r"\sub{" + esc(plain) + "}", len(plain))
+            i += 3
+            continue
+        if card is None and t.type not in ("hr",):
+            card = Card(); cards.append(card)
+        if t.type == "inline" and tokens[i - 1].type == "paragraph_open":
+            tex, plain = inline(t)
+            if depth:
+                marker = esc(f"{ordered[-1]}.") if ordered[-1] else "•"
+                if tokens[i - 2].type == "list_item_open":
+                    card.add(rf"\li{{{depth}}}{{{marker}}}{{{tex}}}", len(plain))
+                    if ordered[-1]: ordered[-1] += 1
+                else:
+                    card.add(rf"\li{{{depth}}}{{}}{{{tex}}}", len(plain))
+            elif quote:
+                card.add(rf"\quoted{{{tex}}}", len(plain))
+            else:
+                card.add(tex + r"\par", len(plain))
+        elif t.type == "bullet_list_open":
+            depth += 1; ordered.append(0)
+        elif t.type == "ordered_list_open":
+            depth += 1; ordered.append(int(t.attrGet("start") or 1))
+        elif t.type in ("bullet_list_close", "ordered_list_close"):
+            depth -= 1; ordered.pop()
+        elif t.type == "blockquote_open":
+            quote += 1
+        elif t.type == "blockquote_close":
+            quote -= 1
+        elif t.type in ("fence", "code_block"):
+            for line in t.content.rstrip("\n").split("\n"):
+                # a kept space is a real glue item, so indents survive in the fit box
+                card.add(r"\codeline{" + esc_code(line).replace(" ", r"\ ") + r"\strut}", len(line) + 30)
+        elif t.type == "hr" and card is not None:
+            card.add(r"\hairline", 10)
+        elif t.type == "table_open":
+            tex, chars, i = table(tokens, i)
+            card.add(tex, chars)
+        i += 1
+    return title, subtitle, [c for c in cards if c.head or c.parts]
+
+
+def layout(cards, box, rng, visitors):
+    """Cut box into one rectangle per card, in reading order, each about the
+    size its text needs at 9.5 pt. Whatever that leaves is dealt in as holes:
+    the flowers and visitors need somewhere to bloom, and a short document gets
+    more garden. Returns [(card index, x, y, w, h)]."""
+    weights = [(k, 900 + 8 * c.chars) for k, c in enumerate(cards)]
+    need = sum(w for _, w in weights)
+    room = box[2] * box[3] - GUTTER * (box[2] + box[3]) * len(cards) ** 0.5
+    spare = max(room - need * 1.15, 0.05 * need)
+    holes = max(visitors, 2 + int(4 * spare / room))
+    for _ in range(holes):
+        # not first: the reader's eye starts at the top left
+        weights.insert(rng.randint(1, len(weights)), (None, max(spare / holes, 0.03 * need)))
+
+    out = []
+    def cut(items, x, y, w, h):
+        if len(items) == 1:
+            if items[0][0] is not None:
+                out.append((items[0][0], round(x, 1), round(y, 1), round(w, 1), round(h, 1)))
+            return
+        whole = sum(v for _, v in items)
+        # the split nearest even, so neither side ends up a sliver
+        best = min(range(1, len(items)), key=lambda n: abs(sum(v for _, v in items[:n]) - whole / 2))
+        s = sum(v for _, v in items[:best]) / whole
+        if w > h * 0.85:     # side by side, first on the left
+            a = (w - GUTTER) * s
+            cut(items[:best], x, y, a, h)
+            cut(items[best:], x + a + GUTTER, y, w - a - GUTTER, h)
+        else:                # stacked, first on top
+            a = (h - GUTTER) * s
+            cut(items[:best], x, y + h - a, w, a)
+            cut(items[best:], x, y, w, h - a - GUTTER)
+    cut(weights, *box)
+    return sorted(out)
+
+
+def macro(k):
+    name = ""
+    k += 1
+    while k:
+        k, r = divmod(k - 1, 26)
+        name = chr(65 + r) + name
+    return r"\content" + name
+
+
+SPOT = 0.35       # a bare fill wider than this, as a fraction of its drawing, is outlined
+PALETTE_HUES = {"neonorange": 28, "neonsky": 205, "neonviolet": 244, "neonrose": 336}
+
+
+def neon_colour(colour):
+    """The sheet's colour nearest an SVG colour; near-black is the page's ground."""
+    h, s, v = colorsys.rgb_to_hsv(colour.red / 255, colour.green / 255, colour.blue / 255)
+    if v < 0.25: return "ground"
+    if s < 0.25: return "neonwhite"
+    return min(PALETTE_HUES, key=lambda c: abs((h * 360 - PALETTE_HUES[c] + 180) % 360 - 180))
+
+
+def read_visitor(svg):
+    """Read an SVG into marks the plant's pen can draw, in paint order, centred,
+    y up, and scaled so everything lies within radius 1. Exits with the reason
+    if the drawing can't be one. A mark is {"colour", "rings", "outlined"} for a
+    bare fill or {"colour", "pts", "width", "closed", "wash"} for a line."""
+    from shapely.geometry import LineString, Polygon
+    from shapely.ops import unary_union
+    from svgelements import SVG, Close, Line, Move, Path as SvgPath, Shape, Text
+    from svgelements import Image as SvgImage
+
+    def refuse(why):
+        sys.exit(f"bloom-sheet: visitor {svg}: {why}")
+
+    def paint(element, attr):
+        """The element's fill or stroke, or None. svgelements reads url(#...) as black."""
+        if "url(" in str(element.values.get(attr, "")):
+            refuse(f"its {attr} is a gradient or pattern; use one flat colour per shape")
+        c = getattr(element, attr)
+        return c if c is not None and c.value is not None else None
+
+    raw = []      # (fill, stroke, stroke width, [(points, closed)])
+    for e in SVG.parse(svg, reify=True).elements():
+        if isinstance(e, Text): refuse("it has text; draw it as paths")
+        if isinstance(e, SvgImage): refuse("it has an embedded image; draw it as paths")
+        if not isinstance(e, Shape): continue
+        fill, stroke = paint(e, "fill"), paint(e, "stroke")
+        if stroke is not None and not e.implicit_stroke_width: stroke = None
+        if fill is None and stroke is None: continue
+        subs = []
+        for seg in SvgPath(e):
+            if isinstance(seg, Move):
+                subs.append([[(seg.end.x, -seg.end.y)], False])
+            elif isinstance(seg, Close):
+                subs[-1][1] = True
+            else:
+                n = 1 if isinstance(seg, Line) else 24
+                subs[-1][0].extend((p.x, -p.y) for p in (seg.point(k / n) for k in range(1, n + 1)))
+        subs = [(pts, closed or math.dist(pts[0], pts[-1]) < 1e-6) for pts, closed in subs if len(pts) > 1]
+        if subs: raw.append((fill, stroke, float(e.implicit_stroke_width or 0), subs))
+    if not raw: refuse("nothing in it has a fill or a stroke")
+
+    every = [p for *_, subs in raw for pts, _ in subs for p in pts]
+    xs, ys = [p[0] for p in every], [p[1] for p in every]
+    cx, cy = (min(xs) + max(xs)) / 2, (min(ys) + max(ys)) / 2
+    radius = max(math.dist(p, (cx, cy)) for p in every) or 1.0
+    unit = lambda pts: [(round((x - cx) / radius, 5), round((y - cy) / radius, 5)) for x, y in pts]
+
+    # all dark would be all cutout: a plain black icon is meant to be seen
+    colours = [c for f, s, *_ in raw for c in (f, s) if c is not None]
+    ink = (lambda c: "neonwhite") if all(neon_colour(c) == "ground" for c in colours) else neon_colour
+
+    marks, covers = [], []
+    touch = radius * 0.005
+    for fill, stroke, width, subs in raw:
+        if fill is not None:
+            area = None
+            for pts, _ in subs:
+                if len(pts) > 2:
+                    poly = Polygon(pts).buffer(0)
+                    area = poly if area is None else area.symmetric_difference(poly)
+            if area is not None: covers.append(area.buffer(touch))
+        if stroke is None:
+            rings = [unit(pts) for pts, _ in subs]
+            xs, ys = [p[0] for r in rings for p in r], [p[1] for r in rings for p in r]
+            big = math.hypot(max(xs) - min(xs), max(ys) - min(ys)) / 2 > SPOT
+            marks.append({"colour": ink(fill), "rings": rings, "outlined": big and ink(fill) != "ground"})
+            continue
+        for pts, closed in subs:
+            marks.append({"colour": ink(stroke), "pts": unit(pts), "width": round(width / radius, 5), "closed": closed,
+                          "wash": ink(fill) if fill is not None and closed else None})
+            covers.append(Polygon(pts).buffer(touch) if closed and len(pts) > 3
+                          else LineString(pts).buffer(width / 2 + touch))
+    whole = unary_union(covers)
+    if whole.geom_type != "Polygon":
+        refuse(f"it comes apart into {len(whole.geoms)} separate pieces; "
+               "join them, or pass each as its own --visitor")
+    return marks
+
+
+def build(args, source):
+    title, subtitle, cards = parse(source, args.level)
+    if args.title is not None: title = args.title
+    if args.subtitle is not None: subtitle = args.subtitle
+    if not cards:
+        sys.exit("bloom-sheet: nothing to put on the page: the document has no headings or text")
+    visitors = [read_visitor(svg) for svg in args.visitor]     # refuse before the two minutes
+    seed = args.seed if args.seed is not None else zlib.crc32(source.encode("utf8")) % 100000
+    rng = random.Random(seed)
+
+    top = H - MARGIN
+    title_tex, title_box, swash = "", None, None
+    if title:
+        # Montserrat Thin runs about 0.56 em a letter; 31 pt is the sheet's title size
+        size = min(31.0, 31.0 * 192 / (0.56 * 10.9 * max(len(title), 1)))
+        width = min(196.0, 0.56 * size * 0.3528 * len(title))
+        title_tex = (r"\node[anchor=south west, inner sep=0pt, text=heading] at (7,278)" "\n"
+                     rf"  {{\thinfont\fontsize{{{size:.1f}}}{{{size:.1f}}}\selectfont {esc(title)}}};" "\n")
+        if subtitle:
+            title_tex += (r"\node[anchor=north west, inner sep=0pt, text=muted, text width=196mm] at (7.4,273.2)" "\n"
+                          rf"  {{\labelfont\fontsize{{5.6}}{{6}}\selectfont {esc(subtitle.upper())}}};" "\n")
+        title_box = [5, H - MARGIN - TITLE_H, 200, TITLE_H]
+        swash = [7, 276.4, 7 + max(30.0, width), 277.2]
+        top = title_box[1] - GUTTER
+
+    rects = layout(cards, (MARGIN, MARGIN, W - 2 * MARGIN, top - MARGIN), rng, len(args.visitor))
+    panels, contents, last = [], [], None
+    for k, x, y, w, h in rects:
+        colour = rng.choice([c for c in COLOURS if c != last]); last = colour
+        panels.append([macro(k)[8:], x, y, w, h, colour, macro(k)])
+        contents.append(rf"\newcommand{{{macro(k)}}}{{%" + "\n" + cards[k].tex() + "}")
+        # 5 pt type is about 1.7 mm of line and 0.9 mm of letter
+        room = (w - 6.2) * (h - 5.6) / (1.8 * 0.95)
+        if cards[k].chars > room:
+            print(f"bloom-sheet: card '{cards[k].head or 'intro'}' will come out under 5 pt: "
+                  "shorten it or split the sheet", file=sys.stderr)
+
+    with tempfile.TemporaryDirectory(prefix="bloom-sheet-") as tmp:
+        d = Path(tmp)
+        (d / "spec.json").write_text(json.dumps(
+            {"seed": seed, "panels": panels, "title_box": title_box, "swash": swash, "visitors": visitors}), encoding="utf8")
+        page = (HERE / "page.tex").read_text(encoding="utf8")
+        for mark, value in (("@@FONTS@@", FONTS), ("@@CONTENTS@@", "\n".join(contents)), ("@@TITLE@@", title_tex)):
+            page = page.replace(mark, value)
+        (d / "sheet.tex").write_text(page, encoding="utf8")
+        grown = run([sys.executable, str(HERE / "grow.py"), "spec.json", "layer.tex"], d, args.verbose)
+        for line in grown.splitlines():
+            if line.startswith("left out: visitor"):
+                print(f"bloom-sheet: {line}", file=sys.stderr)
+        env = dict(os.environ)
+        # the font database takes a minute to build: keep it between sheets
+        cache = Path(os.environ.get("XDG_CACHE_HOME", Path.home() / ".cache")) / "bloom-sheet"
+        try:
+            cache.mkdir(parents=True, exist_ok=True)
+        except OSError:         # a sandbox with no home: slower, not broken
+            cache = d / "cache"
+        env.setdefault("TEXMFVAR", str(cache))
+        latex = ["lualatex", "--no-shell-escape", "--interaction=nonstopmode", "--halt-on-error", "sheet.tex"]
+        for _ in range(2):      # remember picture lands right only on the second pass
+            run(latex, d, args.verbose, env, log="sheet.log")
+        out = Path(args.output)
+        out.parent.mkdir(parents=True, exist_ok=True)
+        if out.suffix.lower() == ".png":
+            run(["pdftoppm", "-r", str(args.dpi), "-png", "-singlefile", "sheet.pdf", "sheet"], d, args.verbose)
+            shutil.copyfile(d / "sheet.png", out)
+        else:
+            shutil.copyfile(d / "sheet.pdf", out)
+    print(f"{out} ({len(cards)} cards, seed {seed})")
+
+
+def run(cmd, cwd, verbose, env=None, log=None):
+    try:
+        p = subprocess.run(cmd, cwd=cwd, env=env, stdout=subprocess.PIPE, stderr=subprocess.STDOUT,
+                           text=True, errors="replace", timeout=600)
+    except FileNotFoundError:
+        sys.exit(f"bloom-sheet: {cmd[0]} is not installed")
+    except subprocess.TimeoutExpired:
+        sys.exit(f"bloom-sheet: {cmd[0]} ran past 10 minutes")
+    if verbose: print(p.stdout)
+    if p.returncode:
+        tail = p.stdout
+        if log and (Path(cwd) / log).exists():
+            text = (Path(cwd) / log).read_text(encoding="utf8", errors="replace")
+            errors = [i for i, line in enumerate(text.splitlines()) if line.startswith("!")]
+            tail = "\n".join(text.splitlines()[errors[0]:errors[0] + 12]) if errors else text[-1500:]
+        sys.exit(f"bloom-sheet: {cmd[0]} failed:\n{tail[-1500:]}")
+    return p.stdout
+
+
+def main():
+    ap = argparse.ArgumentParser(prog="bloom-sheet", description="Turn a markdown document into a one-page neon bloom sheet.")
+    ap.add_argument("input", help="markdown file, or - for stdin")
+    ap.add_argument("-o", "--output", help="output .pdf or .png (default: the input's name, .pdf)")
+    ap.add_argument("--title", help="page title, instead of the document's first top-level heading; empty for none")
+    ap.add_argument("--subtitle", help="small line under the title")
+    ap.add_argument("--level", type=int, default=6, help="headings deeper than this are labels inside a card, not cards (default: every heading is a card)")
+    ap.add_argument("--visitor", action="append", default=[], metavar="SVG", help="an SVG of strokes or one solid shape to perch in the garden; repeat for more (about three suit a page)")
+    ap.add_argument("--seed", type=int, help="plant seed (default: from the document, so a sheet rebuilds the same)")
+    ap.add_argument("--dpi", type=int, default=200, help="PNG resolution (default 200)")
+    ap.add_argument("-v", "--verbose", action="store_true")
+    args = ap.parse_args()
+    source = sys.stdin.read() if args.input == "-" else Path(args.input).read_text(encoding="utf8")
+    if not args.output:
+        args.output = "sheet.pdf" if args.input == "-" else str(Path(args.input).with_suffix(".pdf"))
+    if Path(args.output).suffix.lower() not in (".pdf", ".png"):
+        sys.exit("bloom-sheet: -o must end in .pdf or .png")
+    build(args, source)
+
+
+if __name__ == "__main__":
+    main()

tools/bloom-sheet/grow.py

@@ -0,0 +1,640 @@
+"""Grow the ornament layer of a bloom sheet (see ../SKILL.md).
+
+The page owns its text; this script owns its geometry, in four stages:
+1. motifs: a greedy loop borrowed from florilegium
+   (github.com/kevinraymond/florilegium): find the largest free disc, put a
+   motif in it, mark it taken, repeat. Big discs get flowers; small ones are
+   invisible junctions.
+2. the tree: a minimum spanning tree over the motifs, so the page is one plant.
+3. the vine: the tree cut into a few long paths, each one Catmull-Rom spline
+   carrying a sine wave sized to the room around it; branches leave their
+   parent tangentially.
+4. scrolls: a rinceau. At every crest a scroll leaves the vine and winds into
+   a logarithmic spiral (exponentially rising curvature); scrolls shed smaller
+   counter-winding scrolls, three generations deep, each kept only if it fits.
+5. budding: the largest free gap left pulls a branch out of the nearest stroke
+   that reaches it smoothly; the branch winds into a spiral inside the gap and
+   can itself be budded from. Repeats down to sub-millimetre gaps.
+
+Every line is a weighted stroke: a closed outline offset from a centreline by
+half a width that varies along it, filled rather than stroked. That is
+florilegium's `ribbon` (ink.lua, MIT, Kevin Raymond), ported to Python.
+
+Run:  python grow.py spec.json layer.tex
+spec.json: {"seed": 11, "panels": [[name, x, y, w, h, colour, content macro], ...],
+            "title_box": [x, y, w, h] or null, "swash": [x0, y0, x1, y1] or null,
+            "visitors": [[mark, ...], ...]}
+All lengths are mm from the page's bottom left. A visitor is florilegium's idea
+with the caller's drawing: it takes the largest disc free before the plant
+grows, and the plant grows around it. bloom_sheet.py's read_visitor makes the
+marks, in a unit disc; they are drawn with the plant's own pen.
+"""
+import json, math, random, sys
+from pathlib import Path
+import numpy as np
+
+spec = json.loads(Path(sys.argv[1]).read_text(encoding="utf8"))
+SEED = spec["seed"]
+rng = random.Random(SEED)
+W, H = 210.0, 297.0
+GAP = 0.8           # clearance between anything drawn and a panel edge
+MARGIN = 1.8        # ornaments keep this far from the paper edge; wide enough that
+                    # the vine can pass a full-width panel through the side margins
+
+# ---------------------------------------------------------------- panels
+# name, x, y, w, h (mm from bottom left), colour, content macro
+PANELS = [tuple(p) for p in spec["panels"]]
+# Gutters are 7 mm: narrower, and a scroll has no room to wind. Leave a hole or two
+# open on purpose: the flowers need somewhere to bloom.
+TITLE_BOX = spec["title_box"]   # the title is text, not a panel, but it is not free space
+
+# Corner radii (tl, tr, br, bl). Text starts top left and may reach bottom
+# left, so those stay tight; the right-hand corners open into pockets.
+def radii(w, h):
+    cap = min(w, h) / 3
+    return tuple(min(cap, rng.uniform(lo, hi)) for lo, hi in ((2, 4), (3, 9), (3, 10.5), (2, 7)))
+
+panels = [(n, x, y, w, h, c, m, radii(w, h)) for n, x, y, w, h, c, m in PANELS]
+
+# ---------------------------------------------------------------- distance field
+STEP = 0.4
+gx = np.arange(0, W + STEP / 2, STEP)
+gy = np.arange(0, H + STEP / 2, STEP)
+X, Y = np.meshgrid(gx, gy)
+
+def sd_roundbox(px, py, x, y, w, h, r):
+    """Signed distance to a box with one radius per corner (tl, tr, br, bl).
+    After Inigo Quilez's sdRoundBox, with y pointing up."""
+    tl, tr, br, bl = r
+    cx, cy = x + w / 2, y + h / 2
+    qx, qy = px - cx, py - cy
+    rr = np.where(qx > 0, np.where(qy > 0, tr, br), np.where(qy > 0, tl, bl))
+    ax = np.abs(qx) - w / 2 + rr
+    ay = np.abs(qy) - h / 2 + rr
+    return np.minimum(np.maximum(ax, ay), 0) + np.hypot(np.maximum(ax, 0), np.maximum(ay, 0)) - rr
+
+wall = np.minimum.reduce([X - MARGIN, W - MARGIN - X, Y - MARGIN, H - MARGIN - Y])
+solid = np.full_like(X, np.inf)
+for n, x, y, w, h, c, m, r in panels:
+    solid = np.minimum(solid, sd_roundbox(X, Y, x, y, w, h, r))
+if TITLE_BOX:
+    tx, ty, tw, th = TITLE_BOX
+    solid = np.minimum(solid, sd_roundbox(X, Y, tx, ty, tw, th, (0, 0, 0, 0)))
+clear = np.minimum(solid - GAP, wall)      # room to draw, ignoring ornaments
+free = clear.copy()                        # room to draw, ornaments included
+
+def clear_at(px, py):
+    i = int(round(py / STEP)); j = int(round(px / STEP))
+    if not (0 <= i < clear.shape[0] and 0 <= j < clear.shape[1]): return -1
+    return clear[i, j]
+
+# ---------------------------------------------------------------- weighted strokes
+def normals(pts):
+    out = []
+    for i in range(len(pts)):
+        a = pts[max(i - 1, 0)]; b = pts[min(i + 1, len(pts) - 1)]
+        dx, dy = b[0] - a[0], b[1] - a[1]
+        L = math.hypot(dx, dy) or 1
+        out.append((-dy / L, dx / L))
+    return out
+
+def ribbon(pts, width):
+    """Closed outline of a stroke along pts whose full width at fraction u of
+    its length is width(u)."""
+    nrm = normals(pts)
+    s = [0.0]
+    for i in range(1, len(pts)):
+        s.append(s[-1] + math.dist(pts[i], pts[i - 1]))
+    L = s[-1] or 1
+    left, right = [], []
+    for p, n, si in zip(pts, nrm, s):
+        hw = width(si / L) / 2
+        left.append((p[0] + n[0] * hw, p[1] + n[1] * hw))
+        right.append((p[0] - n[0] * hw, p[1] - n[1] * hw))
+    return left + right[::-1]
+
+def arc_pts(p, q, bend, n=24):
+    """Circular arc from p to q; bend is the sagitta as a fraction of the chord."""
+    (x0, y0), (x1, y1) = p, q
+    mx, my = (x0 + x1) / 2, (y0 + y1) / 2
+    dx, dy = x1 - x0, y1 - y0
+    L = math.hypot(dx, dy)
+    if abs(bend) < 1e-3 or L < 1e-6:
+        return [(x0 + dx * t / n, y0 + dy * t / n) for t in range(n + 1)]
+    s = bend * L
+    R = (L * L / 4 + s * s) / (2 * abs(s))
+    nx, ny = -dy / L, dx / L
+    sign = 1 if s > 0 else -1
+    cx, cy = mx - nx * sign * (R - abs(s)), my - ny * sign * (R - abs(s))
+    a0 = math.atan2(y0 - cy, x0 - cx); a1 = math.atan2(y1 - cy, x1 - cx)
+    da = (a1 - a0 + math.pi) % (2 * math.pi) - math.pi
+    # take the arc on the bulge side
+    midang = a0 + da / 2
+    if (math.cos(midang) * nx + math.sin(midang) * ny) * sign < 0:
+        da = da - 2 * math.pi if da > 0 else da + 2 * math.pi
+    return [(cx + R * math.cos(a0 + da * t / n), cy + R * math.sin(a0 + da * t / n)) for t in range(n + 1)]
+
+def vesica(c, ang, length, fat, n=9):
+    """A pointed petal or leaf: two circular arcs from c to the tip."""
+    tip = (c[0] + length * math.cos(ang), c[1] + length * math.sin(ang))
+    a = arc_pts(c, tip, fat, n)
+    b = arc_pts(tip, c, fat, n)
+    return a + b[1:]
+
+def path(poly):
+    return " -- ".join(f"({x:.2f},{y:.2f})" for x, y in poly) + " -- cycle"
+
+out = []
+def neon(colour, poly, core=0.85):
+    out.append(f"\\neonfill{{{colour}}}{{{int(core * 100)}}}{{{path(poly)}}}")
+def neonline(colour, pts, w0, w1, core=0.9):
+    neon(colour, ribbon(pts, lambda u: w0 + (w1 - w0) * u), core)
+def ring(colour, c, r, w):
+    pts = [(c[0] + r * math.cos(2 * math.pi * k / 24), c[1] + r * math.sin(2 * math.pi * k / 24)) for k in range(25)]
+    # a ring breathes: heavier on one side, like a pen circle
+    ph = rng.uniform(0, 2 * math.pi)
+    neon(colour, ribbon(pts, lambda u: w * (0.55 + 0.45 * math.cos(2 * math.pi * u + ph))), 0.8)
+def dot(colour, c, r):
+    out.append(f"\\neondot{{{colour}}}{{{c[0]:.2f}}}{{{c[1]:.2f}}}{{{r:.2f}}}")
+
+# ---------------------------------------------------------------- motifs
+PALETTE = [("neonorange", 5), ("neonsky", 3), ("neonviolet", 3), ("neonrose", 2)]
+def pick():
+    t = rng.uniform(0, sum(w for _, w in PALETTE))
+    for c, w in PALETTE:
+        t -= w
+        if t <= 0: return c
+    return PALETTE[0][0]
+
+def rosette(c, r, col):
+    n = rng.choice((5, 6, 6, 8))
+    ph = rng.uniform(0, math.pi)
+    for k in range(n):
+        a = ph + 2 * math.pi * k / n
+        petal = vesica(c, a, r, 0.24 if n < 8 else 0.19)
+        out.append(f"\\petalwash{{{col}}}{{{path(petal)}}}")
+        # the petal's outline as one weighted stroke: fat at the belly, thin at the tip
+        neonline_closed(col, petal, 0.34 * min(1, r / 5) + 0.12)
+    ring(pick(), c, r * 0.3, 0.32)
+    dot("neonwhite", c, max(0.35, r * 0.09))
+
+def neonline_closed(col, poly, w):
+    neon(col, ribbon(poly, lambda u: w * (0.25 + 0.75 * math.sin(math.pi * ((2 * u) % 1)) ** 2)), 0.9)
+
+def curl(c, r, col):
+    turns = rng.uniform(1.2, 1.9)
+    a0 = rng.uniform(0, 2 * math.pi)
+    sgn = rng.choice((-1, 1))
+    k = math.log(9) / (turns * 2 * math.pi)       # r falls to a ninth over the turns
+    n = int(22 * turns)
+    pts = []
+    for i in range(n + 1):
+        t = i / n * turns * 2 * math.pi
+        rad = r * math.exp(-k * t)
+        pts.append((c[0] + rad * math.cos(a0 + sgn * t), c[1] + rad * math.sin(a0 + sgn * t)))
+    neonline(col, pts, 0.55 * min(1, r / 3) + 0.15, 0.08)
+    dot(col, pts[-1], max(0.28, r * 0.09))
+
+def sparkle(c, r, col):
+    ph = rng.uniform(0, math.pi / 4)
+    for k in range(4):
+        a = ph + k * math.pi / 2
+        L = r if k % 2 == 0 else r * 0.6
+        tip = (c[0] + L * math.cos(a), c[1] + L * math.sin(a))
+        neon(col, ribbon([c, ((c[0] + tip[0]) / 2, (c[1] + tip[1]) / 2), tip], lambda u: 0.5 * min(1, r / 2.5) * (1 - u) ** 1.4 + 0.02))
+    dot("neonwhite", c, max(0.22, r * 0.1))
+
+def place(c, r):
+    """Choose a motif for a disc of radius r; return (colour, drawn radius,
+    draw). Drawing waits until the vine is known, so a motif the vine could
+    not reach is never drawn. Discs too small for a flower are junctions of
+    the vine and draw nothing: the scrolls carry the small-scale detail."""
+    col = pick()
+    if r >= 3.0:
+        return col, r, lambda: rosette(c, r, col)
+    return col, 0.0, lambda: None
+
+# ---------------------------------------------------------------- visitors
+visitors = []    # (cx, cy, r, marks)
+for number, marks in enumerate(spec.get("visitors", []), 1):
+    i, j = np.unravel_index(np.argmax(free), free.shape)
+    r = min(float(free[i, j]), 15.0)
+    if r < 4.0:
+        print(f"left out: visitor {number}: no free disc wider than {2 * r:.0f} mm")
+        continue
+    c = (float(gx[j]), float(gy[i]))
+    visitors.append((c[0], c[1], r, marks))
+    np.minimum(free, np.hypot(X - c[0], Y - c[1]) - r - 1.0, out=free)
+
+def draw_visitor(cx, cy, r, marks):
+    a = math.radians(rng.uniform(-18, 18))
+    spot = lambda pts: [(cx + r * 0.95 * (x * math.cos(a) - y * math.sin(a)),
+                         cy + r * 0.95 * (x * math.sin(a) + y * math.cos(a))) for x, y in pts]
+    def loop(col, pts, w):     # a closed line breathes like a ring
+        ph = rng.uniform(0, 2 * math.pi)
+        neon(col, ribbon(pts + pts[:1], lambda u: w * (0.75 + 0.25 * math.cos(2 * math.pi * u + ph))), 0.9)
+    for m in marks:
+        if "rings" in m:
+            rings = [spot(ring_) for ring_ in m["rings"]]
+            whole = " ".join(path(ring_) for ring_ in rings)
+            if m["outlined"]:
+                out.append(f"\\begin{{scope}}[even odd rule]\\petalwash{{{m['colour']}}}{{{whole}}}\\end{{scope}}")
+                for ring_ in rings:
+                    loop(m["colour"], ring_, 0.6)
+            else:
+                out.append(f"\\begin{{scope}}[even odd rule]\\neonfill{{{m['colour']}}}{{85}}{{{whole}}}\\end{{scope}}")
+            continue
+        pts = spot(m["pts"])
+        if m["wash"]: out.append(f"\\petalwash{{{m['wash']}}}{{{path(pts)}}}")
+        # the caller's weight, kept within the plant's; an open line swells between thin ends
+        w = max(0.14, min(0.7, m["width"] * r * 0.95))
+        if m["closed"]:
+            loop(m["colour"], pts, w)
+        else:
+            neon(m["colour"], ribbon(pts, lambda u: w * (0.4 + 0.6 * math.sin(math.pi * u) ** 0.7)), 0.9)
+
+# ---------------------------------------------------------------- 1. motifs
+nodes = []       # (cx, cy, drawn radius, colour)
+draws = []
+RMAX = 8.5
+while True:
+    i, j = np.unravel_index(np.argmax(free), free.shape)
+    r = float(free[i, j])
+    if r < 1.0: break
+    r = min(r, RMAX)
+    c = (float(gx[j]), float(gy[i]))
+    col, rd, draw = place(c, r * 0.92)   # drawn a hair smaller than its disc
+    draws.append(draw)
+    # flowers keep a stem's length apart, so the vine between them shows
+    pad = 1.8 if rd >= 3.0 else 0.5
+    np.minimum(free, np.hypot(X - c[0], Y - c[1]) - r - pad, out=free)
+    nodes.append((c[0], c[1], rd, col))
+
+# ---------------------------------------------------------------- 2. the tree
+# Kruskal's minimum spanning tree over every pair of motifs a clear arc can
+# join, shortest gap first. A tree, so the page is one plant and no gutter
+# holds two parallel stems. It fixes topology only; the vine is drawn in 3.
+parent = list(range(len(nodes)))
+def root(a):
+    while parent[a] != a:
+        parent[a] = parent[parent[a]]; a = parent[a]
+    return a
+
+cands = []
+for a in range(len(nodes)):
+    ax, ay, ar, _ = nodes[a]
+    for b in range(a + 1, len(nodes)):
+        bx, by, br, _ = nodes[b]
+        gap = math.hypot(bx - ax, by - ay) - ar - br
+        if 0.4 <= gap <= 24: cands.append((gap, a, b))
+cands.sort()
+edges = []
+for gap, a, b in cands:
+    if root(a) == root(b): continue
+    ax, ay, ar, _ = nodes[a]; bx, by, br, _ = nodes[b]
+    ang = math.atan2(by - ay, bx - ax)
+    p0 = (ax + ar * math.cos(ang), ay + ar * math.sin(ang))
+    p1 = (bx - br * math.cos(ang), by - br * math.sin(ang))
+    if any(all(clear_at(*q) > 0.4 for q in arc_pts(p0, p1, bend, 12)) for bend in (0.0, 0.1, -0.1)):
+        edges.append((a, b)); parent[root(a)] = root(b)
+
+# One plant: whatever the tree could not reach is left out, not drawn alone.
+from collections import Counter
+sizes = Counter(root(k) for k in range(len(nodes)))
+main = sizes.most_common(1)[0][0]
+for g, n in sizes.most_common()[1:]:
+    print("left out:", n, "motif(s) near", [(round(nodes[k][0]), round(nodes[k][1])) for k in range(len(nodes)) if root(k) == g][:3])
+keep = [root(k) == main for k in range(len(nodes))]
+for k in range(len(nodes)):
+    if keep[k]: draws[k]()
+adj = {k: [] for k in range(len(nodes)) if keep[k]}
+for a, b in edges:
+    if keep[a]: adj[a].append(b); adj[b].append(a)
+
+# ---------------------------------------------------------------- 3. the vine
+# The tree is cut into as few long paths as it allows: each walk goes on to
+# the neighbour that turns least, and stops only at a leaf or a hairpin.
+# Every path is one Catmull-Rom spline in one colour, so the vine is
+# tangent-continuous; a branch path borrows its parent's previous node as a
+# phantom control point, so it leaves the parent tangentially, like a shoot.
+def turn(p, q, r):
+    a1 = math.atan2(q[1] - p[1], q[0] - p[0]); a2 = math.atan2(r[1] - q[1], r[0] - q[0])
+    return abs((a2 - a1 + math.pi) % (2 * math.pi) - math.pi)
+
+P = lambda k: nodes[k][:2]
+used = set()
+paths = []       # (phantom node or None, [node ids])
+def walk(phantom, start, first):
+    seq = [start, first]; used.add(frozenset((start, first)))
+    while True:
+        cur, prev = seq[-1], seq[-2]
+        nxt = [n for n in adj[cur] if frozenset((cur, n)) not in used]
+        if not nxt: break
+        n = min(nxt, key=lambda n: turn(P(prev), P(cur), P(n)))
+        if turn(P(prev), P(cur), P(n)) > math.radians(100): break
+        seq.append(n); used.add(frozenset((cur, n)))
+    paths.append((phantom, seq))
+
+leaves = [k for k in adj if len(adj[k]) == 1]
+start = max(leaves, key=lambda k: nodes[k][0] - nodes[k][1]) if leaves else next(iter(adj))
+walk(None, start, adj[start][0])
+pending = True
+while pending:
+    pending = False
+    for phantom_, seq in list(paths):
+        for idx, k in enumerate(seq):
+            for n in adj[k]:
+                if frozenset((k, n)) in used: continue
+                # phantom: the path neighbour of k the branch continues most smoothly from
+                nbrs = [seq[i] for i in (idx - 1, idx + 1) if 0 <= i < len(seq)]
+                ph = min(nbrs, key=lambda m: turn(P(m), P(k), P(n))) if nbrs else None
+                walk(ph, k, n); pending = True
+
+def catmull(ctrl, per):
+    out = []
+    for i in range(1, len(ctrl) - 2):
+        p0, p1, p2, p3 = ctrl[i - 1], ctrl[i], ctrl[i + 1], ctrl[i + 2]
+        for k in range(per):
+            t = k / per; t2 = t * t; t3 = t2 * t
+            out.append(tuple(0.5 * (2 * p1[j] + (-p0[j] + p2[j]) * t + (2 * p0[j] - 5 * p1[j] + 4 * p2[j] - p3[j]) * t2
+                                    + (-p0[j] + 3 * p1[j] - 3 * p2[j] + p3[j]) * t3) for j in (0, 1)))
+    out.append(ctrl[-2])
+    return out
+
+def mirror(a, b):     # a phantom beyond b, continuing a -> b straight on
+    return (2 * b[0] - a[0], 2 * b[1] - a[1])
+
+def resample(curve, ds):
+    out = [curve[0]]; carry = 0.0
+    for p, q in zip(curve, curve[1:]):
+        seg = math.dist(p, q); t = ds - carry
+        while t <= seg:
+            out.append((p[0] + (q[0] - p[0]) * t / seg, p[1] + (q[1] - p[1]) * t / seg)); t += ds
+        carry = seg - (t - ds)
+    if math.dist(out[-1], curve[-1]) > 1e-6: out.append(curve[-1])
+    return out
+
+def heading(curve, i):
+    a = curve[max(i - 1, 0)]; b = curve[min(i + 1, len(curve) - 1)]
+    return math.atan2(b[1] - a[1], b[0] - a[0])
+
+def wavy(centre, ph0):
+    """Lay a sine wave along a smooth centreline. Wavelength and amplitude
+    follow the room at each point (phase is integrated, so a changing
+    wavelength never kinks), and the wave fades to nothing at both ends so
+    paths meet their junctions exactly. Returns the curve and its crests as
+    (index, side), side +1 for a crest on the left of travel."""
+    pts = resample(centre, 0.2)
+    L = 0.2 * (len(pts) - 1)
+    out, crests = [], []
+    ph = ph0; last = math.cos(ph)
+    for i, p in enumerate(pts):
+        c = clear_at(*p)
+        s = 0.2 * i
+        fade = max(0.0, min(1.0, s / 1.6, (L - s) / 1.6))
+        amp = max(0.0, min(1.4, 0.55 * (c - 0.45))) * fade
+        th = heading(pts, i)
+        off = amp * math.sin(ph)
+        out.append((p[0] - math.sin(th) * off, p[1] + math.cos(th) * off))
+        ph += 2 * math.pi * 0.2 / max(5.0, min(11.0, 4.2 * c))
+        now = math.cos(ph)
+        if fade > 0.6 and amp > 0.2 and (last > 0) != (now > 0):
+            crests.append((i, 1 if last > 0 else -1))
+        last = now
+    return out, crests
+pos = {k: P(k) for k in adj}
+
+room = clear + 0.5   # scrolls are hairlines: they may come closer to a panel than the vine
+def mark(pts, rad):
+    """Take a band of radius rad around a polyline out of the free room."""
+    dense = []
+    for p, q in zip(pts, pts[1:]):
+        n = max(1, int(math.dist(p, q) / 0.3))
+        dense += [(p[0] + (q[0] - p[0]) * t / n, p[1] + (q[1] - p[1]) * t / n) for t in range(n)]
+    dense.append(pts[-1])
+    k = int(math.ceil((rad + 0.5) / STEP))
+    for x, y in dense:
+        i, j = int(round(y / STEP)), int(round(x / STEP))
+        win = (slice(max(i - k, 0), i + k + 1), slice(max(j - k, 0), j + k + 1))
+        np.minimum(room[win], np.hypot(X[win] - x, Y[win] - y) - rad, out=room[win])
+def room_at(x, y):
+    i = int(round(y / STEP)); j = int(round(x / STEP))
+    if not (0 <= i < room.shape[0] and 0 <= j < room.shape[1]): return -1
+    return room[i, j]
+
+for vx, vy, vr, _ in visitors:
+    mark([(vx, vy)], vr)
+
+vines = []       # (pts, colour, w0, w1)
+for n_path, (phantom, seq) in enumerate(paths):
+    pts_n = [pos[k] for k in seq]
+    head = pos[phantom] if phantom is not None else mirror(pts_n[1], pts_n[0])
+    ctrl = [head] + pts_n + [mirror(pts_n[-2], pts_n[-1])]
+    curve, crests = wavy(catmull(ctrl, 8), rng.uniform(0, 2 * math.pi))
+    col = nodes[seq[0]][3] if phantom is None else pick()
+    w0 = 0.5 if phantom is None else 0.38
+    vines.append((curve, col, w0, 0.2, crests))
+
+for k in adj:
+    if nodes[k][2] > 0: mark([P(k)], nodes[k][2] + 0.3)
+for curve, col, w0, w1, crests in vines:
+    mark(curve, w0 / 2 + 0.25)
+
+# ---------------------------------------------------------------- 4. scrolls
+# The fractal part, after the rinceau: a scroll leaves its parent almost
+# tangentially and winds into a logarithmic spiral, because its curvature
+# grows exponentially along it. Partway along, it sheds smaller scrolls that
+# wind the other way, and those shed smaller ones again: nested S-curves, all
+# tangent-continuous with what they grow from. Each is kept only where it fits.
+scrolls = []     # (pts, colour, w0)
+leaves_out = []
+
+def scroll_pts(base, theta, turn_dir, L, ds=0.18):
+    R0 = 0.5 * L
+    g = math.log(10)
+    pts = [base]; th = theta; x, y = base
+    s = 0.0; heads = [theta]
+    while s < L:
+        k = math.exp(g * s / L) / R0
+        th += turn_dir * k * ds
+        x += ds * math.cos(th); y += ds * math.sin(th)
+        pts.append((x, y)); heads.append(th); s += ds
+    return pts, heads
+
+def scroll(base, theta, turn_dir, L, w0, depth, col, skip=0.55):
+    fit = None
+    for scale in (1.0, 0.75, 0.55, 0.4):
+        Ls = L * scale
+        if Ls < 0.9: return False
+        for td in (turn_dir, -turn_dir) if depth == 3 else (turn_dir,):
+            pts, heads = scroll_pts(base, theta, td, Ls)
+            wmax = w0 / 2 + 0.08
+            if all(room_at(*q) > wmax for q in pts if math.dist(q, base) > skip):
+                fit = (pts, heads, Ls, td); break
+        if fit: break
+    if not fit: return False
+    pts, heads, Ls, td = fit
+    width = lambda u: w0 * (1 - 0.85 * u) + 0.035
+    scrolls.append((pts[::2] + [pts[-1]], col, w0))
+    mark(pts[1:], w0 / 2 + 0.2)
+    if rng.random() < 0.35:
+        dot(rng.choice(("neonwhite", col)), pts[-1], 0.2)
+    if depth > 1:
+        n = len(pts)
+        for frac in (0.2, 0.42):
+            i = int(frac * n)
+            # peel off on the outside of the bend and wind the other way
+            scroll(pts[i], heads[i] - td * math.radians(18), -td, Ls * 0.5, width(i / n) * 0.85, depth - 1, col)
+        i = int(0.62 * n)
+        if rng.random() < 0.5:
+            la = heads[i] + td * math.radians(rng.uniform(35, 55))
+            ll = min(1.6, Ls * 0.3)
+            lt = (pts[i][0] + ll * math.cos(la), pts[i][1] + ll * math.sin(la))
+            if room_at(*lt) > 0.15 and room_at((pts[i][0] + lt[0]) / 2, (pts[i][1] + lt[1]) / 2) > 0.3:
+                leaves_out.append((col, vesica(pts[i], la, ll, 0.32))); mark([pts[i], lt], 0.35)
+    return True
+
+order = list(range(len(vines)))
+rng.shuffle(order)
+for n_path in order:
+    curve, col, w0, w1, crests = vines[n_path]
+    # Rinceau: at each crest a scroll carries straight on and winds back
+    # toward the stem, into the bay the wave curves around.
+    for i, side in crests:
+        th = heading(curve, i)
+        # a scroll the size of the bay it winds into
+        amp = max(0.0, min(1.4, 0.55 * (clear_at(*curve[i]) - 0.45)))
+        L = max(1.8, min(7.0, 1.2 + 3.4 * amp))
+        # it leaves at an angle: a scroll tangent to its parent runs alongside
+        # it for a millimetre and reads as a thickening, not a branch
+        scroll(curve[i], th + side * math.radians(22), -side, L, 0.3, 3, col, skip=0.9)
+    # and the vine's end does not stop: it winds up into a scroll of its own
+    th = heading(curve, len(curve) - 1)
+    L = max(2.0, min(6.0, 2.0 * clear_at(*curve[-1])))
+    scroll(curve[-1], th, rng.choice((-1, 1)), L, w1 + 0.05, 3, col)
+
+# ---------------------------------------------------------------- 5. budding
+# Growing outward from the vine always leaves holes it happened to miss.
+# So the gaps call the growth instead, florilegium's grown loop: take the
+# largest free disc left, and bud a branch into it from the existing stroke
+# that reaches it most smoothly; the branch winds up into a spiral inside the
+# disc. Every branch becomes somewhere later branches can bud from, so big
+# holes fill first and small ones last, as deep as the space allows.
+anchors = []     # (x, y, heading, width, colour)
+def add_anchors(pts, col, wfun):
+    n = len(pts)
+    for i in range(0, n, 2):
+        anchors.append((pts[i][0], pts[i][1], heading(pts, i), wfun(i / max(n - 1, 1)), col))
+for curve, col, w0, w1, crests in vines:
+    add_anchors(curve, col, lambda u, w0=w0, w1=w1: w0 + (w1 - w0) * u)
+for pts, col, w0 in scrolls:
+    add_anchors(pts, col, lambda u, w0=w0: w0 * (1 - 0.85 * u) + 0.035)
+
+def bezier(p0, p1, p2, p3, n):
+    out = []
+    for k in range(n + 1):
+        t = k / n; a = (1 - t) ** 3; b = 3 * (1 - t) ** 2 * t; c = 3 * (1 - t) * t * t; d = t ** 3
+        out.append((a * p0[0] + b * p1[0] + c * p2[0] + d * p3[0], a * p0[1] + b * p1[1] + c * p2[1] + d * p3[1]))
+    return out
+
+def bud_into(cx, cy, r):
+    """Try to grow a branch from a nearby stroke into the disc (c, r)."""
+    A = np.array([(a[0], a[1]) for a in anchors])
+    d = np.hypot(A[:, 0] - cx, A[:, 1] - cy)
+    near = np.argsort(d)[:24]
+    tries = []
+    for k in near:
+        ax, ay, th, aw, col = anchors[k]
+        to_c = math.atan2(cy - ay, cx - ax)
+        for flip in (0, math.pi):          # a stroke can be budded from either way along it
+            dev = (to_c - (th + flip) + math.pi) % (2 * math.pi) - math.pi
+            if abs(dev) > math.radians(115): continue
+            tries.append((d[k] * (1 + 0.9 * abs(dev) / math.pi), k, th + flip, dev))
+    tries.sort()
+    for score, k, th, dev in tries[:16]:
+        ax, ay, _, aw, col = anchors[k]
+        # leave the parent at no more than ~50 degrees, toward the disc
+        t0 = th + max(-1, min(1, dev / math.radians(50))) * math.radians(min(50, abs(math.degrees(dev))))
+        w = max(0.06, min(aw * 0.8, 0.1 + 0.11 * r))
+        rho0 = 0.72 * r
+        u = math.atan2(cy - ay, cx - ax)
+        for sense in (1 if dev > 0 else -1, -1 if dev > 0 else 1):
+            phi0 = u - sense * math.pi / 2
+            pe = (cx + rho0 * math.cos(phi0), cy + rho0 * math.sin(phi0))
+            L = math.dist((ax, ay), pe)
+            # a bud reaches its gap from close by; a long stalk reads as a stray wire
+            if L < 0.3 or L > 1.0 + 2.5 * r: continue
+            kk = L / 3
+            stalk = bezier((ax, ay), (ax + kk * math.cos(t0), ay + kk * math.sin(t0)),
+                           (pe[0] - kk * math.cos(u), pe[1] - kk * math.sin(u)), pe, max(4, int(L / 0.25)))
+            spiral = []
+            for i in range(1, 25):
+                t = i / 24
+                ph = phi0 + sense * 2.3 * math.pi * t
+                rho = rho0 * math.exp(-math.log(7) * t)
+                spiral.append((cx + rho * math.cos(ph), cy + rho * math.sin(ph)))
+            pts = stalk + spiral
+            if all(room_at(*q) > w / 2 + 0.04 for q in pts if math.dist(q, (ax, ay)) > max(0.45, aw)):
+                return pts, col, w
+    return None
+
+buds = 0
+while True:
+    i, j = np.unravel_index(np.argmax(room), room.shape)
+    r = float(room[i, j])
+    if r < 0.42: break
+    cx, cy = float(gx[j]), float(gy[i])
+    got = bud_into(cx, cy, min(r, 6.0))
+    if got is None:
+        # nothing can reach this hole: close its middle so the loop moves on
+        mark([(cx, cy)], min(r, 6.0) * 0.35)
+        continue
+    pts, col, w = got
+    scrolls.append((pts, col, w))
+    mark(pts[1:], w / 2 + 0.16)
+    add_anchors(pts, col, lambda u, w=w: w * (1 - 0.85 * u) + 0.035)
+    if r > 0.9 and rng.random() < 0.4:
+        dot(rng.choice(("neonwhite", col)), pts[-1], min(0.25, 0.12 + 0.05 * r))
+    buds += 1
+
+# ---------------------------------------------------------------- strokes out
+stem_out = []
+for curve, col, w0, w1, crests in vines:
+    stem_out.append((col, ribbon(curve[::2] + [curve[-1]], lambda u, w0=w0, w1=w1: w0 + (w1 - w0) * u)))
+for pts, col, w0 in scrolls:
+    stem_out.append((col, ribbon(pts, lambda u, w0=w0: w0 * (1 - 0.85 * u) + 0.035)))
+stem_out += leaves_out
+nodes = [n for n, kk in zip(nodes, keep) if kk]
+
+# ---------------------------------------------------------------- title swash
+# One long weighted stroke under the title, ending in a curl.
+swash_out = []
+if spec.get("swash"):
+    sx0, sy0, sx1, sy1 = spec["swash"]
+    swash = arc_pts((sx0, sy0), (sx1, sy1), -0.012, 60)
+    swash_out = [ribbon(swash, lambda u: 0.15 + 0.85 * math.sin(math.pi * u ** 0.8) ** 1.5)]
+
+# ---------------------------------------------------------------- write
+lines = [f"% generated by {Path(__file__).name}, seed {SEED}. Do not edit; run the script."]
+lines.append("\\begin{scope}% stems and leaves")
+for col, poly in stem_out:
+    lines.append(f"\\neonfill{{{col}}}{{75}}{{{path(poly)}}}")
+lines.append("\\end{scope}")
+lines.append("\\begin{scope}% panel frames")
+for n, x, y, w, h, c, m, (tl, tr, br, bl) in panels:
+    p = (f"({x + bl:.2f},{y:.2f}) -- ({x + w - br:.2f},{y:.2f}) arc[start angle=-90, end angle=0, radius={br:.2f}] "
+         f"-- ({x + w:.2f},{y + h - tr:.2f}) arc[start angle=0, end angle=90, radius={tr:.2f}] "
+         f"-- ({x + tl:.2f},{y + h:.2f}) arc[start angle=90, end angle=180, radius={tl:.2f}] "
+         f"-- ({x:.2f},{y + bl:.2f}) arc[start angle=180, end angle=270, radius={bl:.2f}] -- cycle")
+    lines.append(f"\\neonframe{{{c}}}{{{p}}}")
+lines.append("\\end{scope}")
+for poly in swash_out:
+    lines.append(f"\\neonfill{{neonorange}}{{90}}{{{path(poly)}}}")
+for vx, vy, vr, marks in visitors:
+    draw_visitor(vx, vy, vr, marks)
+lines.extend(out)
+for n, x, y, w, h, c, m, r in panels:
+    lines.append(f"\\panel{{{x}}}{{{y}}}{{{w}}}{{{h}}}{{{c}}}{{{m}}}")
+dst = Path(sys.argv[2])
+dst.write_text("\n".join(lines) + "\n", encoding="utf8")
+print(f"seed {SEED}: {len(nodes)} motifs, {len(paths)} vine paths, {len(scrolls)} scrolls ({buds} budded) -> {dst.name}")

tools/bloom-sheet/page.tex

@@ -0,0 +1,103 @@
+% A bloom sheet: one A4 page, GameCult navy with a neon garden.
+% bloom_sheet.py fills the three @@ markers; grow.py writes layer.tex.
+% Every panel is a fitting tcolorbox, so its type shrinks to whatever room it gets.
+\documentclass{article}
+\usepackage[paperwidth=210mm,paperheight=297mm,margin=0mm]{geometry}
+\usepackage{fontspec}
+\usepackage{xcolor}
+\usepackage{tikz}
+\usepackage{array}
+\usepackage[most]{tcolorbox}
+\tcbuselibrary{fitting}
+
+% ---------- GameCult palette (gamecult-site quartz.config.ts), plus neon ----------
+\definecolor{ground}{HTML}{07111A}
+\definecolor{groundtop}{HTML}{03070D}
+\definecolor{groundfoot}{HTML}{09141F}
+\definecolor{panelbg}{HTML}{0A1722}
+\definecolor{heading}{HTML}{EEF5FF}
+\definecolor{body}{HTML}{B7C7D9}
+\definecolor{muted}{HTML}{7488A0}
+\definecolor{neonorange}{HTML}{FF8A2A}
+\definecolor{neonsky}{HTML}{59B7FF}
+\definecolor{neonviolet}{HTML}{8F84FF}
+\definecolor{neonrose}{HTML}{FF6FAE}  % not a brand colour: the "cozy" note
+\definecolor{neonwhite}{HTML}{EEF5FF}
+\colorlet{accent}{neonorange}
+
+@@FONTS@@
+
+% ---------- Neon primitives, called by the generated layer ----------
+% A filled weighted stroke with two halos; #2 is the percent of colour the core keeps.
+\newcommand{\neonfill}[3]{\path[
+  preaction={draw=#1, line width=1.7pt, draw opacity=0.09, line join=round},
+  preaction={draw=#1, line width=0.8pt, draw opacity=0.18, line join=round},
+  fill=#1!#2!white] #3;}
+\newcommand{\neondot}[4]{%
+  \fill[#1, opacity=0.10] (#2,#3) circle ({2.4*#4});
+  \fill[#1, opacity=0.22] (#2,#3) circle ({1.5*#4});
+  \fill[#1!55!white] (#2,#3) circle (#4);}
+\newcommand{\petalwash}[2]{\fill[#1, opacity=0.14] #2;}
+\newcommand{\neonframe}[2]{%
+  \fill[panelbg, opacity=0.88] #2;
+  \draw[#1, line width=3pt, opacity=0.06] #2;
+  \draw[#1, line width=1.4pt, opacity=0.14] #2;
+  \draw[#1!70!white, line width=0.45pt] #2;}
+
+% ---------- Text atoms ----------
+% All of these live in the preamble: a macro with parameters defined inside a
+% panel's argument breaks tcolorbox fit ("Illegal parameter number"). Nothing
+% here sets an absolute size for body text: fit scales the base size and size
+% commands escape it. \sub is the one relative label.
+\newcommand{\head}[1]{{\labelfont\color{accent}\MakeUppercase{#1}}\par\vspace{0.25em}}
+\newcommand{\sub}[1]{\par\vspace{0.25em}{\labelfont\color{muted}\MakeUppercase{#1}}\par}
+% \leavevmode: a \color at the start of a table cell otherwise drops the cell a line.
+\DeclareRobustCommand{\code}[1]{\leavevmode{\numfont\color{neonsky}#1}}
+\DeclareRobustCommand{\strong}[1]{\leavevmode{\bfseries\color{heading}#1}}
+\DeclareRobustCommand{\soft}[1]{\leavevmode{\speakfont\color{heading}#1}}
+\DeclareRobustCommand{\faint}[1]{\leavevmode{\color{muted}#1}}
+% One list item: depth, its marker, its text.
+\newcommand{\li}[3]{\par{\leftskip=\dimexpr #1em - 1em\relax\hangindent=1em\hangafter=1\noindent\makebox[1em][l]{\color{accent}#2}#3\par}}
+\newcommand{\quoted}[1]{\par{\leftskip=0.8em\color{heading}#1\par}}
+\newcommand{\codeline}[1]{\par{\numfont\color{neonsky}\hangindent=1em\hangafter=1\noindent#1\par}}
+\newcommand{\hairline}{\par\vspace{0.2em}{\color{muted}\rule{\linewidth}{0.2pt}}\par\vspace{0.2em}}
+\newcommand{\cell}[1]{\raggedright\arraybackslash#1}
+
+% ---------- One panel ----------
+% \panel{x}{y}{w}{h}{colour}{content}, mm from the page's bottom left.
+% The frame is drawn by the generated layer; this only sets the text.
+% Padding 3.1mm keeps text clear of corner radii up to ~10mm.
+\newcommand{\panel}[6]{%
+  \node[anchor=south west, inner sep=0pt] at (#1mm,#2mm) {%
+    \begin{tcolorbox}[blank, fit, width=#3mm, height=#4mm,
+      left=3.1mm, right=3.1mm, top=3mm, bottom=2.6mm,
+      fontupper=\color{body}\linespread{1.02}\selectfont,
+      before upper={\colorlet{accent}{#5}\parindent0pt\parskip0.14em\raggedright}]
+    #6
+    \end{tcolorbox}};}
+
+@@CONTENTS@@
+
+\pagecolor{ground}
+\pagestyle{empty}
+\begin{document}
+\begin{tikzpicture}[remember picture, overlay, x=1mm, y=1mm]
+\begin{scope}[shift={(current page.south west)}]
+
+% ---- ground: the site's vertical gradient and its three coloured radials ----
+% Radials are stacks of faint circles; one opaque-ish circle shows a hard edge.
+\shade[top color=groundtop, bottom color=groundfoot, middle color=ground] (0,0) rectangle (210,297);
+\foreach \i in {1,...,32} {
+  \fill[neonviolet, opacity=0.0060] (38,267) circle ({87*\i/32});
+  \fill[neonsky, opacity=0.0050] (109,297) circle ({100*\i/32});
+  \fill[neonorange, opacity=0.0065] (164,255) circle ({65*\i/32});
+}
+\foreach \i in {1,...,24} {\fill[neonrose, opacity=0.0028] (40,30) circle ({60*\i/24});}
+
+\input{layer.tex}
+
+@@TITLE@@
+
+\end{scope}
+\end{tikzpicture}
+\end{document}

tools/bloom-sheet/test_visitors.py

@@ -0,0 +1,71 @@
+#!/usr/bin/env python3
+"""What a visitor must be. Run: python3 test_visitors.py
+Needs python3-svgelements and python3-shapely; no LaTeX."""
+import math, sys, tempfile
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent))
+from bloom_sheet import read_visitor
+
+fails = 0
+tmp = Path(tempfile.mkdtemp())
+
+
+def svg(body):
+    f = tmp / "v.svg"
+    f.write_text(f'<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 100 100">{body}</svg>')
+    return str(f)
+
+
+def check(name, ok):
+    global fails
+    print(("ok  " if ok else "FAIL"), name)
+    fails += not ok
+
+
+def refused(name, body, reason):
+    try:
+        read_visitor(svg(body))
+        check(f"{name}: refused", False)
+    except SystemExit as e:
+        check(f"{name}: refused for {reason}", reason in str(e))
+
+
+DISC = '<circle cx="50" cy="50" r="40" fill="#f80"/>'
+refused("apart", '<circle cx="20" cy="20" r="8" fill="#f80"/><circle cx="80" cy="80" r="8" fill="#f80"/>', "2 separate")
+refused("apart lines", '<path d="M5 5 L20 5 M5 90 L20 90" fill="none" stroke="#f80"/>', "2 separate")
+refused("gradient", '<circle cx="50" cy="50" r="40" fill="url(#g)"/>', "gradient")
+refused("gradient stroke", '<circle cx="50" cy="50" r="40" fill="none" stroke="url(#g)"/>', "gradient")
+refused("text", DISC + '<text x="5" y="5">hi</text>', "text")
+refused("image", DISC + '<image width="9" height="9" xlink:href="data:image/png;base64,iVBORw0KGgo="/>', "image")
+refused("nothing", '<circle cx="50" cy="50" r="40" fill="none"/>', "fill or a stroke")
+
+m = read_visitor(svg(DISC))
+check("a large bare fill is outlined, not solid", len(m) == 1 and m[0]["outlined"] and m[0]["colour"] == "neonorange")
+m = read_visitor(svg('<path d="M10 10 L90 10 L50 90" fill="none" stroke="#59B7FF" stroke-width="2"/>'))
+check("a stroke is an open line, no wash", len(m) == 1 and "pts" in m[0] and not m[0]["closed"] and m[0]["wash"] is None)
+check("the line keeps its colour", m[0]["colour"] == "neonsky")
+check("the stroke width scales with the drawing", 0 < m[0]["width"] < 0.1)
+m = read_visitor(svg('<circle cx="50" cy="50" r="40" fill="#8F84FF" stroke="#FF8A2A" stroke-width="1"/>'))
+check("a fill under a stroke is a wash", m[0]["closed"] and m[0]["wash"] == "neonviolet" and m[0]["colour"] == "neonorange")
+m = read_visitor(svg('<path d="M50 5 L95 95 L5 95Z"/>'))
+check("an all-black icon is seen", m[0]["colour"] == "neonwhite")
+m = read_visitor(svg(DISC + '<circle cx="35" cy="35" r="5" fill="#07111A"/>'))
+check("black on colour is a cutout", m[1]["colour"] == "ground" and not m[1]["outlined"])
+m = read_visitor(svg(DISC + '<circle cx="35" cy="35" r="5" fill="#59B7FF"/>'))
+check("a small bare fill stays solid", not m[1]["outlined"])
+m = read_visitor(svg('<circle cx="50" cy="50" r="40" fill="#07111A"/><circle cx="50" cy="50" r="5" fill="#f80"/>'))
+check("a large cutout stays a cutout", m[0]["colour"] == "ground" and not m[0]["outlined"])
+m = read_visitor(svg(DISC + '<circle cx="35" cy="35" r="5" fill="#07111A"/>'))
+check("paint order is kept", [x["colour"] for x in m] == ["neonorange", "ground"])
+m = read_visitor(svg('<circle cx="50" cy="50" r="40" fill="none" stroke="#f80"/><circle cx="35" cy="35" r="5" fill="#fff"/><circle cx="65" cy="35" r="5" fill="#fff"/>'))
+check("eyes inside an outline count as touching", len(m) == 3)
+m = read_visitor(svg('<path fill-rule="evenodd" fill="#f80" d="M10 10 H90 V90 H10Z M40 40 H60 V60 H40Z"/>'))
+check("a hole stays a ring of the solid", len(m) == 1 and len(m[0]["rings"]) == 2)
+m = read_visitor(svg('<g transform="translate(30 10) scale(0.2)"><rect width="100" height="300" fill="#f80"/></g>'))
+pts = [p for ring in m[0]["rings"] for p in ring]
+check("any drawing lands in the unit disc", abs(max(math.hypot(*p) for p in pts) - 1) < 1e-3)
+top = max(pts, key=lambda p: p[1])
+check("y points up", top[1] > 0 and m[0]["rings"][0][0][1] > 0)
+
+sys.exit(1 if fails else 0)

tools/cargo-mutants.sh

@@ -0,0 +1,389 @@
+#!/usr/bin/env bash
+# cargo-mutants on Yggdrasil for a revision range: ONE verify job, per-file scoped
+# tests, survivors confirmed on the full suite, sharded over free slots, one merged
+# survivor list. The one owner of "run cargo-mutants" (no brief, no job script runs
+# an inline `cargo mutants`).
+#
+#   SUMMARY=<log> tools/cargo-mutants.sh <local-repo> <rev> <base> [workdir]
+#     workdir   directory inside the repo where cargo runs (a package or workspace
+#               member, e.g. crates/mind-body; CultLib has no Cargo.toml at its root).
+#               The mutated range is `git diff --relative <base> <rev>` taken at the
+#               WORKSPACE ROOT: cargo-mutants matches --in-diff paths, -f paths and
+#               prints mutant names relative to the workspace root, not to workdir.
+#     env       FILTERS  '<path>=<filter>,...' overrides a file's derived test filter
+#                        (path as the mutant names print it); '-' = full suite
+#               TEST_ARGS  harness args, e.g. '--skip flaky_one' (a flaky test would
+#                        make a surviving mutant read as killed in one run)
+#               NAMES    local file of mutant names (one per line, copied from a
+#                        previous MISSED/TIMEOUT list): skips stage 1 and the listing
+#                        and runs only those names on the full suite. This is the rerun
+#                        after killing survivors with tests.
+#               SHARDS (3) JOBS (2) MIN_TEST_TIMEOUT (20) CONFIRM_TIMEOUT_MULT (5)
+#               TIMEOUT  seconds for the whole job (default 10800)
+#               everything else tools/stopgap/ygg-verify.sh reads (MEM, CPUS, ...)
+#     Typical, from an agent: launch as ONE background shell with a fresh log, then
+#       tools/stopgap/ygg-verify.sh wait <log>   (Bash tool timeout >= 280000 ms)
+#     Run it ONCE per pass, at the end, on the final spelling of the code. Chasing
+#     survivors is a NAMES rerun, never a second whole-range sweep.
+#
+# STAGES (all inside the one job and the one host driver):
+#   plan     one container writes the range diff, lists every mutant in it, derives each
+#            touched file's test filter and counts the tests that filter selects
+#            (`cargo test -- <filter> --list`, one build for all files).
+#   stage 1  each touched file whose filter selects tests runs its mutants against that
+#            file's tests only (`cargo mutants -f <file> -- <filter>`). The filter is
+#            derived from the path: the module path after the last src/ (a/mod.rs ->
+#            `a::`, a/b.rs -> `a::b::`); lib.rs, main.rs, bin/ and files outside src/
+#            have none. FILTERS overrides. Stage 1 decides only CAUGHT (its own green
+#            filtered baseline guards false kills) and UNVIABLE (a build fact). Its
+#            MISSED and TIMEOUT are never reported: a mutant that only another module's
+#            tests or tests/ kill survives a filtered run. A file whose filter selects 0
+#            tests (tests=0) never runs stage 1: all its mutants go to stage 2.
+#   stage 2  every name stage 1 did not settle (survivors, files without a filter,
+#            zero-test files, or NAMES) runs on the full suite in cargo-mutants' own
+#            baseline, sharded over the containers. Stage 2 ALWAYS runs: that baseline is
+#            the only full-suite check, so a red suite is a red job even when stage 1
+#            settled every mutant (one name then rides along; its outcome is dropped).
+#            The test timeout is max(MIN_TEST_TIMEOUT, CONFIRM_TIMEOUT_MULT x baseline);
+#            the generous default keeps a slow-but-finishing test from flipping a
+#            MISSED mutant to TIMEOUT with the host's load. Its outcome is final.
+#   merge    each name counted once; MISSED and TIMEOUT are stage-2 outcomes only.
+# Containers per stage: min(SHARDS, SLOTS, units, 1 + free slots now), units being the
+# stage's files (stage 1) or names (stage 2). The job holds one slot (ygg-verify's);
+# the driver leases further slot locks with flock -n, never waits for one, takes none
+# while /proc/pressure/io full avg60 > 20, and releases them when each stage ends. A
+# killed job (YGG_KILLED) starts nothing further.
+#
+# OUTPUT: the YGG-SUMMARY/$YGG_NONCE lines ygg-verify's summary carries; per-container
+# logs stay on the host and go with the job.
+#   FILTER <file> <filter> tests=<n> mutants=<m>      one per stage-1 file (zero-test first)
+#   MUTANTS tested=N caught=C missed=M timeout=T unviable=U | stage1 filtered=F
+#     survivors=S confirmed_caught=X | containers=K | plan=..s stage1=..s/<k1> stage2=..s/<k2> | <m>m
+#   MISSED <name> / TIMEOUT <name>                    final outcomes, at most 50
+#   ERROR ...      a red baseline, a container that failed, mutants with no outcome:
+#                  the job exits non-zero and prints no MUTANTS line
+# Exit 0 when every stage ran on a green baseline; survivors do not fail the job (the
+# score is not a gate). cargo-mutants exits 2 (missed) and 3 (timeouts) normally; 4 is a
+# red baseline; anything else is an error.
+#
+# DELETION LINE: this file dies with tools/stopgap/ygg-verify.sh when `idunn verify`
+# ships a typed mutation step. Modes in this one file: no flag = launcher on the
+# workstation; --host = the driver on the Yggdrasil host (ygg-verify.sh RUN_ON_HOST=1);
+# --plan / --item = the work inside a container.
+set -euo pipefail
+
+SUMTAG="YGG-SUMMARY${YGG_NONCE:+/$YGG_NONCE}"
+sum() { printf '%s: %s\n' "$SUMTAG" "$*"; }
+
+# ---- --escape: mutant names on stdin -> one anchored -F pattern per line ----------------------
+# Only regex metacharacters are escaped, so names holding * + ( ) | stay literal; ^...$ pins the whole name.
+if [ "${1:-}" = --escape ]; then
+  exec perl -pe 'chomp; s/([\\.+*?()|\[\]{}^\$])/\\$1/g; $_ = "^$_\$\n"'
+fi
+
+# ---- launcher (workstation) -------------------------------------------------
+if [ "${1:-}" != --host ] && [ "${1:-}" != --plan ] && [ "${1:-}" != --item ]; then
+  here=$(cd "$(dirname "$0")" && pwd)
+  repo=${1:?usage: cargo-mutants.sh <local-repo> <rev> <base> [workdir]}
+  rev=${2:?revision}; base=${3:?base revision}; workdir=${4:-.}
+  : "${SHARDS:=3}" "${JOBS:=2}" "${MIN_TEST_TIMEOUT:=20}" "${CONFIRM_TIMEOUT_MULT:=5}" "${TIMEOUT:=10800}"
+  for v in SHARDS JOBS MIN_TEST_TIMEOUT TIMEOUT; do
+    case ${!v} in ''|*[!0-9]*|0) echo "cargo-mutants: $v must be a positive integer" >&2; exit 2 ;; esac
+  done
+  case $CONFIRM_TIMEOUT_MULT in ''|*[!0-9.]*|.*|*.|*.*.*) echo "cargo-mutants: CONFIRM_TIMEOUT_MULT must be a positive number" >&2; exit 2 ;; esac
+  if [ -n "${FILTERS:-}" ]; then
+    old=$IFS; IFS=,
+    for f in $FILTERS; do
+      case $f in ?*=?*) ;; *) IFS=$old; echo "cargo-mutants: FILTERS entries are <path>=<filter>" >&2; exit 2 ;; esac
+    done
+    IFS=$old
+  fi
+  sha_rev=$(git -C "$repo" rev-parse --verify "$rev^{commit}") || { echo "cargo-mutants: unknown revision" >&2; exit 2; }
+  sha_base=$(git -C "$repo" rev-parse --verify "$base^{commit}") || { echo "cargo-mutants: unknown base revision" >&2; exit 2; }
+  git -C "$repo" merge-base --is-ancestor "$sha_base" "$sha_rev" || { echo "cargo-mutants: base is not an ancestor of rev (the verify mirror carries only rev's history)" >&2; exit 2; }
+  stage=$(mktemp -d)
+  trap 'rm -rf "$stage"' EXIT
+  cp "$here/cargo-mutants.sh" "$stage/"
+  files=(cargo-mutants.sh)
+  if [ -n "${NAMES:-}" ]; then
+    [ -r "$NAMES" ] || { echo "cargo-mutants: cannot read the NAMES file" >&2; exit 2; }
+    tr -d '\r' <"$NAMES" >"$stage/names.txt"; files+=(names.txt)
+  fi
+  bundle=$(tar -C "$stage" -cz "${files[@]}" | base64 | tr -d '\n')
+  # The driver runs on the host: it unpacks the bundle into its own directory (mounted read-only into every container) and removes it when done.
+  cmd=$(printf 'd=$(mktemp -d) && echo %s | base64 -d | tar -xz -C "$d" && WORKDIR=%q BASE=%q FILTERS=%q TEST_ARGS=%q SHARDS=%q JOBS=%q MIN_TEST_TIMEOUT=%q CONFIRM_TIMEOUT_MULT=%q CM_NAMES=%q CM_DIR="$d" bash "$d/cargo-mutants.sh" --host' \
+    "$bundle" "$workdir" "$sha_base" "${FILTERS:-}" "${TEST_ARGS:-}" "$SHARDS" "$JOBS" "$MIN_TEST_TIMEOUT" "$CONFIRM_TIMEOUT_MULT" "${NAMES:+1}")
+  RUN_ON_HOST=1 TIMEOUT=$TIMEOUT "$here/stopgap/ygg-verify.sh" "$repo" "$sha_rev" rust "$cmd"
+  exit $?
+fi
+
+# ---- driver (Yggdrasil host, inside the job's slot) --------------------------
+if [ "$1" = --host ]; then
+  : "${YGG_WORK:?not started by ygg-verify.sh RUN_ON_HOST=1}" "${YGG_IMAGE:?}" "${YGG_CNAME:?}" "${YGG_LABEL:?}" "${YGG_SLOTS:?}" "${YGG_ROOT:?}"
+  D=${CM_DIR:?}
+  set +e   # every docker step is checked by hand: a container exits non-zero by design
+  export LC_ALL=C
+  t0=$(date +%s)
+  LEASE_FDS=()
+  unlease() { local lf; for lf in "${LEASE_FDS[@]}"; do exec {lf}>&-; done; LEASE_FDS=(); }
+  cleanup() {
+    local p; for p in $(jobs -p); do kill "$p" 2>/dev/null; done
+    unlease
+    # containers write as root
+    [ -z "$D" ] || [ "$D" = / ] || sudo rm -rf -- "$D"
+  }
+  trap cleanup EXIT; trap 'exit 143' TERM INT HUP
+  killed() { [ -n "${YGG_KILLED:-}" ] && [ -e "$YGG_KILLED" ]; }
+  now() { date +%s; }
+  # The shared volume is CARGO_HOME itself so sibling containers share cargo's package-cache lock; a registry-only mount left
+  # the lock in each container's layer and concurrent unpacks removed each other's crate directories (2026-11-03).
+  # Every container carries the job label (the stopgap's watchdog kills by it) and the same caps.
+  common=(--label "$YGG_LABEL" "--cpus=${YGG_CPUS:-4}" "--memory=${YGG_MEM:-6g}"
+    -v "$YGG_WORK:/seed:ro" -v "$D:/cm:ro" -v /etc/machine-id:/etc/machine-id:ro
+    -v eureka-cargo-home:/cargo-home -v eureka-nuget:/root/.nuget/packages -v eureka-sccache:/sccache
+    -e BASH_ENV=/tmp/.ygg-bash-env -e CARGO_HOME=/cargo-home
+    -e "WORKDIR=${WORKDIR:-.}" -e "BASE=$BASE" -e "TEST_ARGS=${TEST_ARGS:-}" -e "FILTERS=${FILTERS:-}" -e "CM_NAMES=${CM_NAMES:-}" -e "JOBS=$JOBS"
+    -e "MIN_TEST_TIMEOUT=$MIN_TEST_TIMEOUT" -e "CONFIRM_TIMEOUT_MULT=$CONFIRM_TIMEOUT_MULT"
+    -e GIT_CONFIG_COUNT=1 -e GIT_CONFIG_KEY_0=safe.directory -e 'GIT_CONFIG_VALUE_0=*')
+  [ -z "${YGG_NONCE:-}" ] || common+=(-e "YGG_NONCE=$YGG_NONCE")
+  pre="printf 'set -o pipefail\n' >/tmp/.ygg-bash-env"
+  # drun <name> <out dir> [-e flags]: one container (the half named by $MODE), its output to <out>/stdout, its
+  # status in <out>/hostrc. A killed job starts nothing (125). DOCKER_ARGS is a flag string, split on purpose.
+  # shellcheck disable=SC2086
+  drun() {
+    local name=$1 out=$2 rc; shift 2
+    killed && return 125
+    mkdir -p "$out"
+    sudo nice -n 10 docker run --rm --name "$name" "${common[@]}" -v "$out:/out" "$@" -w /src ${DOCKER_ARGS:-} "$YGG_IMAGE" \
+      bash -o pipefail -c "$pre; bash /cm/cargo-mutants.sh $MODE" >"$out/stdout" 2>&1
+    rc=$?; echo "$rc" >"$out/hostrc"; return "$rc"
+  }
+  killed_exit() { sum "JOB KILLED by the watchdog before the run finished; no totals"; exit 124; }
+  mkdir -p "$D/items" "$D/plan" "$D/q" "$D/m"
+
+  # ---- plan
+  tp=$(now)
+  MODE=--plan drun "$YGG_CNAME-plan" "$D/plan"
+  rc=$?
+  killed && killed_exit
+  if [ "$rc" != 0 ]; then
+    sum "ERROR the plan container exited $rc: the range diff or the mutant listing failed"
+    tail -n 6 "$D/plan/stdout" 2>/dev/null | sed "s|^|$SUMTAG: ERROR   |"
+    exit 2
+  fi
+  tp=$(( $(now) - tp ))
+  if [ "${CM_NAMES:-}" = 1 ]; then sort -u "$D/names.txt" >"$D/m/universe"
+  else sort -u "$D/plan/names.txt" >"$D/m/universe"; fi
+  for f in s1.caught s1.unviable s1.surv s1.names; do : >"$D/m/$f"; done
+
+  # lease <units>: the containers of a stage = min(SHARDS, SLOTS, units, 1 + free slots now); sets K and holds the leases
+  lease() {
+    local want=$1 i lf psi
+    [ "$want" -le "$SHARDS" ] || want=$SHARDS
+    [ "$want" -le "$YGG_SLOTS" ] || want=$YGG_SLOTS
+    K=1; [ "$want" -gt 1 ] || return 0
+    psi=$(awk '$1 == "full" { for (i = 2; i <= NF; i++) if ($i ~ /^avg60=/) { sub("avg60=", "", $i); print $i } }' "${CM_PSI:-/proc/pressure/io}" 2>/dev/null)
+    if awk -v p="${psi:-0}" 'BEGIN { exit !(p > 20) }'; then return 0; fi
+    for i in $(seq 1 "$YGG_SLOTS"); do
+      [ "$K" -lt "$want" ] || break
+      exec {lf}>"$YGG_ROOT/slot-$i.lock"
+      if flock -n "$lf"; then LEASE_FDS+=("$lf"); K=$((K + 1)); else exec {lf}>&-; fi
+    done
+  }
+  # run_stage <stage> <count> <fn>: K workers claim items 1..count by mkdir, in order (largest first)
+  run_stage() {
+    local stage=$1 count=$2 fn=$3 w pids=()
+    for w in $(seq 1 "$K"); do
+      ( for lf in "${LEASE_FDS[@]}"; do exec {lf}>&-; done   # the lease belongs to the driver, never to a child (2026-09-23 inherited-fd scar)
+        i=0
+        while [ "$i" -lt "$count" ]; do
+          i=$((i + 1))
+          killed && break
+          [ ! -e "$D/failed" ] || break
+          mkdir "$D/q/$stage-$i" 2>/dev/null || continue
+          "$fn" "$i"
+        done ) &
+      pids+=($!)
+    done
+    wait "${pids[@]}"
+  }
+  container_error() {   # container_error <label> <out dir>
+    local rc; rc=$(cat "$2/hostrc" 2>/dev/null)
+    sum "ERROR $1 container exited ${rc:-?} (4 is a red baseline: the unmutated tests failed there)"
+    tail -n 25 "$2/stdout" 2>/dev/null | sed "s|^|$SUMTAG: ERROR   |"
+  }
+
+  # ---- stage 1: files whose filter selects tests (the plan container derived each file's filter and counted its tests)
+  S1_FILE=(); S1_FILTER=(); s1n=0
+  if [ "${CM_NAMES:-}" != 1 ]; then
+    while IFS=$'\t' read -r cnt file f t; do      # files by mutant count, largest first
+      [ "$t" != 0 ] || continue                   # a filter that selects no test settles nothing: straight to stage 2
+      s1n=$((s1n + 1)); S1_FILE[$s1n]=$file; S1_FILTER[$s1n]=$f
+      awk -F: -v f="$file" '$1 == f' "$D/m/universe" >"$D/items/s1-$s1n.names"
+    done <"$D/plan/filters.txt"
+  fi
+  s1_item() {
+    local n=$1 rc
+    MODE=--item drun "$YGG_CNAME-s1-$n" "$D/items/s1-$n/out" -e CM_STAGE=1 -e "CM_FILE=${S1_FILE[$n]}" -e "CM_FILTER=${S1_FILTER[$n]}"
+    rc=$?
+    if [ "$rc" != 0 ] && ! killed; then touch "$D/failed"; fi
+  }
+  K1=0; ts1=0
+  if [ "$s1n" -gt 0 ]; then
+    ts1=$(now)
+    lease "$s1n"; K1=$K
+    run_stage s1 "$s1n" s1_item
+    unlease
+    killed && killed_exit
+    ts1=$(( $(now) - ts1 ))
+    bad=0
+    for n in $(seq 1 "$s1n"); do
+      o="$D/items/s1-$n/out"
+      if [ "$(cat "$o/hostrc" 2>/dev/null)" != 0 ]; then
+        [ -e "$D/q/s1-$n" ] || continue   # never started: the job is already red for another file
+        container_error "stage 1 (${S1_FILE[$n]})" "$o"; bad=1; continue
+      fi
+    done
+    if [ "$bad" != 0 ] || [ -e "$D/failed" ]; then exit 1; fi
+  fi
+  # FILTER lines: the anomalies (0 tests) first, then the rest, at most 12 in all
+  if [ "${CM_NAMES:-}" != 1 ]; then
+    { awk -F'\t' '$4 == 0' "$D/plan/filters.txt"; awk -F'\t' '$4 != 0' "$D/plan/filters.txt"; } |
+      awk -F'\t' '{ if (NR <= 12) printf "FILTER %s %s tests=%s mutants=%s\n", $2, $3, $4, $1; else h++ } END { if (h) printf "FILTER ... %d more files\n", h }' |
+      while IFS= read -r l; do sum "$l"; done
+  fi
+  for n in $(seq 1 "$s1n"); do
+    o="$D/items/s1-$n/out"
+    cat "$D/items/s1-$n.names" >>"$D/m/s1.names"
+    cat "$o/caught.txt" >>"$D/m/s1.caught"; cat "$o/unviable.txt" >>"$D/m/s1.unviable"
+    cat "$o/missed.txt" "$o/timeout.txt" >>"$D/m/s1.surv"
+  done
+  # only names of this run's range count; stage 1 settles caught and unviable, nothing else
+  for f in s1.caught s1.unviable s1.surv s1.names; do
+    sort -u "$D/m/$f" | comm -12 - "$D/m/universe" >"$D/m/$f.t" && mv "$D/m/$f.t" "$D/m/$f"
+  done
+  cat "$D/m/s1.caught" "$D/m/s1.unviable" | sort -u >"$D/m/s1.settled"
+  comm -23 "$D/m/universe" "$D/m/s1.settled" >"$D/s2.txt"
+  # Stage 2 always runs, so cargo-mutants' full-suite baseline always does (cargo-mutants runs no baseline for an
+  # empty selection). With every name settled it carries one name; the merge drops that name's outcome.
+  if [ -s "$D/s2.txt" ]; then bash "$D/cargo-mutants.sh" --escape <"$D/s2.txt" >"$D/s2.re"
+  else head -n 1 "$D/m/universe" | bash "$D/cargo-mutants.sh" --escape >"$D/s2.re"; fi
+
+  # ---- stage 2: the full suite on everything stage 1 did not settle
+  s2n=$(wc -l <"$D/s2.re" | tr -d " ")
+  K2=0; ts2=0
+  for l in caught missed timeout unviable; do : >"$D/m/s2.$l"; done
+  s2_shard() {
+    local k=$1 rc
+    MODE=--item drun "$YGG_CNAME-s2-$k" "$D/items/s2-$k/out" -e CM_STAGE=2 -e "CM_SHARD=$((k - 1))/$K2"
+    rc=$?
+    if [ "$rc" != 0 ] && ! killed; then touch "$D/failed"; fi
+  }
+  if [ "$s2n" -gt 0 ]; then
+    ts2=$(now)
+    lease "$s2n"; K2=$K
+    run_stage s2 "$K2" s2_shard
+    unlease
+    killed && killed_exit
+    ts2=$(( $(now) - ts2 ))
+    bad=0
+    for k in $(seq 1 "$K2"); do
+      o="$D/items/s2-$k/out"
+      if [ "$(cat "$o/hostrc" 2>/dev/null)" != 0 ]; then
+        [ -e "$D/q/s2-$k" ] || continue
+        container_error "stage 2 (shard $k of $K2)" "$o"; bad=1; continue
+      fi
+      for l in caught missed timeout unviable; do cat "$o/$l.txt" >>"$D/m/s2.$l"; done
+    done
+    if [ "$bad" != 0 ] || [ -e "$D/failed" ]; then exit 1; fi
+  fi
+
+  # ---- merge: a name's outcome is stage 2's where it ran, else stage 1's; each name once
+  for l in caught missed timeout unviable; do
+    sort -u "$D/m/s2.$l" | comm -12 - "$D/s2.txt" >"$D/m/s2.$l.t" && mv "$D/m/s2.$l.t" "$D/m/s2.$l"
+  done
+  cat "$D/m/s2.caught" "$D/m/s2.missed" "$D/m/s2.timeout" "$D/m/s2.unviable" | sort -u >"$D/m/s2.all"
+  nout=$(comm -23 "$D/s2.txt" "$D/m/s2.all" | wc -l | tr -d ' ')
+  if [ "$nout" != 0 ]; then
+    sum "ERROR $nout mutants selected for the full-suite run have no outcome in any shard (a name unknown to cargo-mutants at this revision, or a shard that died)"
+    exit 1
+  fi
+  C=$(cat "$D/m/s1.caught" "$D/m/s2.caught" | sort -u | wc -l | tr -d ' ')
+  U=$(cat "$D/m/s1.unviable" "$D/m/s2.unviable" | sort -u | wc -l | tr -d ' ')
+  M=$(wc -l <"$D/m/s2.missed" | tr -d ' '); T=$(wc -l <"$D/m/s2.timeout" | tr -d ' ')
+  S=$(wc -l <"$D/m/s1.surv" | tr -d ' '); F=$(wc -l <"$D/m/s1.names" | tr -d ' ')
+  X=$(comm -12 "$D/m/s1.surv" "$D/m/s2.caught" | wc -l | tr -d ' ')
+  K=$K1; [ "$K2" -le "$K" ] || K=$K2
+  sum "MUTANTS tested=$((C + M + T + U)) caught=$C missed=$M timeout=$T unviable=$U | stage1 filtered=$F survivors=$S confirmed_caught=$X | containers=$K | plan=${tp}s stage1=${ts1}s/${K1} stage2=${ts2}s/${K2} | $(awk -v e="$(( $(now) - t0 ))" 'BEGIN { printf "%.1f", e / 60 }')m"
+  { sed 's/^/MISSED /' "$D/m/s2.missed"; sed 's/^/TIMEOUT /' "$D/m/s2.timeout"; } >"$D/m/surv.txt"
+  total=$(wc -l <"$D/m/surv.txt" | tr -d ' ')
+  head -n 50 "$D/m/surv.txt" | while IFS= read -r l; do sum "$l"; done
+  if [ "$total" -gt 50 ]; then
+    sum "... $((total - 50)) more MISSED/TIMEOUT names; they follow in the job log as cm-survivor lines"
+    tail -n +51 "$D/m/surv.txt" | sed 's/^/cm-survivor: /'
+  fi
+  exit 0
+fi
+
+# ---- inside a container -----------------------------------------------------
+set +e
+# overridable only so tools/test-tools.sh can run this half against a mock
+SRC=${CM_SRC:-/src}; CM=${CM_DIR:-/cm}; OUT=${CM_OUT:-/out}; SEED=${CM_SEED:-/seed}
+if [ -d "$SEED" ]; then mkdir -p "$SRC" && cp -a "$SEED/." "$SRC/" || { echo "cannot copy $SEED into $SRC"; exit 2; }; fi
+cd "$SRC/${WORKDIR:-.}" || { echo "BAD WORKDIR"; exit 2; }
+set -f; read -ra targs <<<"${TEST_ARGS:-}"; set +f
+if [ "$1" = --plan ]; then
+  wsroot=$(dirname "$(cargo locate-project --workspace --message-format plain)") || { echo "cargo locate-project failed"; exit 2; }
+  git -C "$wsroot" diff --relative "$BASE" HEAD >"$OUT/d" || { echo "git diff of the range failed"; exit 2; }
+  cargo mutants --list --in-diff "$OUT/d" >"$OUT/names.txt" 2>"$OUT/list.err" || { echo "cargo mutants --list failed"; tail -n 5 "$OUT/list.err"; exit 2; }
+  : >"$OUT/filters.txt"
+  [ "$CM_NAMES" != 1 ] || exit 0
+  # stage 1's plan: each touched file's test filter and how many tests it selects (0 = nothing for stage 1 to run)
+  declare -A fover
+  if [ -n "${FILTERS:-}" ]; then
+    IFS=, read -ra fl <<<"$FILTERS"
+    for e in "${fl[@]}"; do fover[${e%%=*}]=${e#*=}; done
+  fi
+  derive_filter() {   # derive_filter <path>: the test filter of a file, nothing for the full suite
+    local p=$1 rest
+    if [ -n "${fover[$p]+x}" ]; then [ "${fover[$p]}" = - ] || echo "${fover[$p]}"; return 0; fi
+    case $p in */src/*.rs|src/*.rs) ;; *) return 0 ;; esac
+    rest=${p##*src/}; rest=${rest%.rs}
+    case $rest in lib|main|bin/*|*/bin/*) return 0 ;; esac
+    rest=${rest%/mod}
+    echo "${rest//\//::}::"
+  }
+  built=0
+  while IFS=$'\t' read -r cnt file; do      # files by mutant count, largest first
+    f=$(derive_filter "$file")
+    [ -n "$f" ] || continue
+    if [ "$built" = 0 ]; then
+      cargo test --no-run >"$OUT/build.log" 2>&1 || { echo "cargo test --no-run failed"; tail -n 5 "$OUT/build.log"; exit 2; }
+      built=1
+    fi
+    t=$(cargo test -- "$f" "${targs[@]}" --list 2>/dev/null | awk '/^[0-9]+ tests?, / { s += $1 } END { print s + 0 }')
+    printf '%s\t%s\t%s\t%s\n' "$cnt" "$file" "$f" "$t" >>"$OUT/filters.txt"
+  done < <(awk -F: '{ c[$1]++ } END { for (f in c) print c[f] "\t" f }' "$OUT/names.txt" | sort -t "$(printf '\t')" -k1,1nr -k2)
+  exit 0
+fi
+# --item: stage 1 (CM_FILE with its CM_FILTER) or stage 2 (shard CM_SHARD of the names in $CM/s2.re)
+o=${CM_TMP:-/tmp}/cmo
+args=(mutants --in-diff "$CM/plan/d" -o "$o" --jobs "$JOBS" --minimum-test-timeout "$MIN_TEST_TIMEOUT")
+tail_args=()
+if [ "$CM_STAGE" = 1 ]; then
+  args+=(-f "$CM_FILE")
+  tail_args=(-- "$CM_FILTER"); [ "${#targs[@]}" = 0 ] || tail_args+=(-- "${targs[@]}")
+else
+  mapfile -t res <"$CM/s2.re"
+  for r in "${res[@]}"; do args+=(-F "$r"); done
+  args+=(--timeout-multiplier "$CONFIRM_TIMEOUT_MULT")
+  case $CM_SHARD in */1) ;; *) args+=(--shard "$CM_SHARD") ;; esac
+  [ "${#targs[@]}" = 0 ] || tail_args=(-- -- "${targs[@]}")
+fi
+cargo "${args[@]}" "${tail_args[@]}" >"$OUT/cargo.log" 2>&1
+rc=$?
+for l in caught missed timeout unviable; do cp "$o/mutants.out/$l.txt" "$OUT/$l.txt" 2>/dev/null || : >"$OUT/$l.txt"; done
+echo "$rc" >"$OUT/rc"
+tail -n 30 "$OUT/cargo.log"
+# 0 clean, 2 missed and 3 timeouts are normal; 4 (red baseline) and everything else are errors
+case $rc in 0|2|3) exit 0 ;; *) exit "$rc" ;; esac

tools/context-pack.py

@@ -1,21 +1,26 @@
 #!/usr/bin/env python3
 """Carry a cut_spec's file_changes anchors from the spec's base to a worktree.
 
-Usage: context-pack.py <cut_spec id> <worktree> [--since <sha>] [--only <k>[,<k>...]]
+Usage: context-pack.py <cut_spec id> <worktree> [--since <sha>] [--only <k>|r<k>[,...]]
                        [--spec-json <file>] [--max-lines <n>]
 
-Prints a header, a status table (one line per anchor) and bounded windows of the
-code each anchor names, numbered in the worktree's lines. Exit: 0 every anchor
-carried; 3 an anchor cannot be carried (OUT_OF_RANGE, UNRESOLVED, GONE outside
+Prints a header, a status table (one line per anchor: file_changes as <k>, reads
+as r<k>) and bounded windows of the code each anchor names, numbered in the
+worktree's lines: edit windows, then READ windows, then one caller list per
+distinct symbol. A symbol an anchor names must be in its mapped window or the
+status gains SYMBOL_MISSING. Exit: 0 every anchor carried; 3 an anchor cannot be
+carried (OUT_OF_RANGE, UNRESOLVED, MISSING read, SYMBOL_MISSING, GONE outside
 the spec's deletes); 2 usage; 4 spec unreadable. Standard library plus git.
 Errors name a field and a code, never an input value.
---max-lines bounds the windows, not the table: the table always lists every
-anchor, so a budget smaller than the table prints the table and no window.
+--max-lines bounds the windows and caller lists, not the table: the table always
+lists every anchor, so a budget smaller than the table prints the table and no
+window. Precedence: table, edit windows, read windows, caller lists.
 """
 import argparse
 import json
 import os
 import re
+import shlex
 import subprocess
 import sys
 
@@ -26,6 +31,12 @@ WINDOW_CAP = 100
 CONTEXT = 3
 DEFAULT_MAX_LINES = 800
 HUNK = re.compile(r"^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@")
+MAX_CALLER_SYMBOLS = 8
+MAX_CALLER_HITS = 50
+MAX_CALLER_FILES = 20
+HIT_TEXT = 160
+ONLY = re.compile(r"^(r?)([0-9]+)$")
+IDENT = re.compile(r"^[A-Za-z0-9_]+$")
 HEX = re.compile(r"^[0-9a-fA-F]{7,40}$")
 
 
@@ -84,6 +95,17 @@ def check_spec_shape(spec):
         raise Fail(4, "spec: %s: InvalidInput" % field)
     if not isinstance(spec["base"], str):
         bad("base")
+    def check_loc(at, loc):
+        if not isinstance(loc, dict):
+            bad(at)
+        if not isinstance(loc.get("path"), str):
+            bad(at + ".path")
+        if not is_int(loc.get("line")):
+            bad(at + ".line")
+        if loc.get("end_line") is not None and not is_int(loc["end_line"]):
+            bad(at + ".end_line")
+        if loc.get("symbol") is not None and not isinstance(loc["symbol"], str):
+            bad(at + ".symbol")
     fcs = spec["file_changes"]
     if not isinstance(fcs, list):
         bad("file_changes")
@@ -91,17 +113,21 @@ def check_spec_shape(spec):
         at = "file_changes[%d]" % k
         if not isinstance(fc, dict):
             bad(at)
-        loc = fc.get("location")
-        if not isinstance(loc, dict):
-            bad(at + ".location")
-        if not isinstance(loc.get("path"), str):
-            bad(at + ".location.path")
-        if not is_int(loc.get("line")):
-            bad(at + ".location.line")
-        if loc.get("end_line") is not None and not is_int(loc["end_line"]):
-            bad(at + ".location.end_line")
+        check_loc(at + ".location", fc.get("location"))
         if "change" in fc and not isinstance(fc["change"], str):
             bad(at + ".change")
+    reads = spec.get("reads")
+    if reads is None:
+        reads = []
+    if not isinstance(reads, list):
+        bad("reads")
+    for k, rd in enumerate(reads, 1):
+        at = "reads[%d]" % k
+        if not isinstance(rd, dict):
+            bad(at)
+        check_loc(at + ".location", rd.get("location"))
+        if "why" in rd and not isinstance(rd["why"], str):
+            bad(at + ".why")
     dels = spec.get("deletes", [])
     if not isinstance(dels, list):
         bad("deletes")
@@ -236,12 +262,34 @@ def safe_path(path):
         and ".." not in path.replace("\\", "/").split("/")
 
 
-def resolve(tree, k, fc, deleted_ok, base_ok, listed):
+def has_symbol(symbol, lines):
+    text = "\n".join(lines)
+    if IDENT.match(symbol):
+        return re.search(r"(?<![A-Za-z0-9_])" + re.escape(symbol) + r"(?![A-Za-z0-9_])", text) is not None
+    return symbol in text
+
+
+def resolve(tree, label, fc, deleted_ok, base_ok, listed, read=False):
+    """One anchor: carried to the worktree, then its symbol (if any) looked up in
+    the mapped window (the AT BASE window for GONE)."""
+    a = carry_anchor(tree, label, fc, deleted_ok, base_ok, listed, read)
+    sym = fc["location"].get("symbol")
+    a["symbol"] = sym or None
+    if sym and a["window"]:
+        kind, path, s, e = a["window"]
+        lines = tree.base_lines(path) if kind == "base" else tree.wt_lines(path)
+        if lines is not None and not has_symbol(sym, lines[s - 1:e]):
+            a["status"] += " SYMBOL_MISSING " + sym
+            a["exit"] = 3
+    return a
+
+
+def carry_anchor(tree, label, fc, deleted_ok, base_ok, listed, read):
     loc = fc["location"]
     path, s = loc["path"], int(loc["line"])
     e = int(loc.get("end_line") or s)
-    a = {"k": k, "path": path, "s": s, "e": e, "change": str(fc.get("change", "")),
-         "rank": 1, "exit": 0, "status": "", "now": None, "window": None}
+    a = {"k": label, "path": path, "s": s, "e": e, "change": str(fc.get("change", "")),
+         "rank": 1, "exit": 0, "status": "", "now": None, "window": None, "read": read}
     if not base_ok:
         a.update(rank=0, exit=3, status="UNRESOLVED base not a commit here: git fetch origin " + tree.base)
         return a
@@ -249,6 +297,9 @@ def resolve(tree, k, fc, deleted_ok, base_ok, listed):
         a.update(rank=0, exit=3, status="UNRESOLVED path or git diff unusable")
         return a
     base = tree.base_lines(path)
+    if base is None and read:
+        a.update(rank=0, exit=3, status="MISSING (read path absent at base)")
+        return a
     if base is None:
         sib = [p for p in tree.siblings() if p.rsplit("/", 1)[-1] == path.rsplit("/", 1)[-1]][:3]
         a.update(rank=0, status="NEW" + (" (at base: " + ", ".join(sib) + ")" if sib else ""))
@@ -285,7 +336,7 @@ def resolve(tree, k, fc, deleted_ok, base_ok, listed):
 
 
 def table_line(a):
-    line = "[%d] %s:%d-%d  %s" % (a["k"], a["path"], a["s"], a["e"], a["status"])
+    line = "[%s] %s:%d-%d  %s" % (a["k"], a["path"], a["s"], a["e"], a["status"])
     if a["now"]:
         line += "  -> %s:%d-%d" % a["now"]
     return line + "  # " + " ".join(a["change"].split())[:70]
@@ -294,7 +345,8 @@ def table_line(a):
 def window_body(tree, a):
     kind, path, s, e = a["window"]
     lines = tree.base_lines(path) if kind == "base" else tree.wt_lines(path)
-    cap = "== [%d] %s:%d-%d%s  %s" % (a["k"], path, s, e, " AT BASE" if kind == "base" else "", a["status"])
+    where = "%s:%d-%d%s  %s" % (path, s, e, " AT BASE" if kind == "base" else "", a["status"])
+    cap = ("== READ %s: %s  (%s)" % (a["k"], a["change"][:200], where)) if a["read"] else "== [%s] %s" % (a["k"], where)
     if lines is None:
         return cap, ["(file not readable in the worktree)"]
     lo, hi = max(1, s - CONTEXT), min(len(lines), e + CONTEXT)
@@ -318,6 +370,46 @@ def overlaps_since(tree, since, a):
     return False
 
 
+def caller_list(wt, symbol, windows):
+    """The lines of one CALLERS list: hits of the symbol in the worktree outside
+    every mapped window of the spec."""
+    args = ["grep", "-n", "-I", "--no-color", "-z", "-F"] + (["-w"] if IDENT.match(symbol) else []) + ["-e", symbol]
+    raw = git(wt, *args) or b""
+    hits = []
+    for rec in raw.decode("utf-8", "replace").split("\n"):
+        parts = rec.split("\0", 2)
+        if len(parts) < 3 or not parts[1].isdigit():
+            continue
+        path, n = parts[0], int(parts[1])
+        if any(path == wp and ws <= n <= we for wp, ws, we in windows):
+            continue
+        hits.append((path, n, parts[2].rstrip("\r")))
+    counts = {}
+    for path, _, _ in hits:
+        counts[path] = counts.get(path, 0) + 1
+    out = ["CALLERS %s: %d hits in %d files" % (symbol, len(hits), len(counts))]
+    if len(hits) <= MAX_CALLER_HITS:
+        out += ["%s:%d: %s" % (path, n, text[:HIT_TEXT]) for path, n, text in hits]
+    else:
+        ranked = sorted(counts.items(), key=lambda kv: (-kv[1], kv[0]))
+        out += ["%6d  %s" % (c, path) for path, c in ranked[:MAX_CALLER_FILES]]
+        if len(ranked) > MAX_CALLER_FILES:
+            out.append("(%d more files)" % (len(ranked) - MAX_CALLER_FILES))
+        out.append("narrow: git grep -n -I %s-F -e %s -- <path>" % ("-w " if IDENT.match(symbol) else "", shlex.quote(symbol)))
+    return out
+
+
+def parse_only(text, p):
+    """Labels: <k> for file_changes, r<k> for reads."""
+    labels = set()
+    for x in text.split(","):
+        m = ONLY.match(x)
+        if not m:
+            p.error("")
+        labels.add(m.group(1) + str(int(m.group(2))))
+    return labels
+
+
 def main(argv):
     p = Parser(prog="context-pack.py")
     p.add_argument("spec_id")
@@ -329,19 +421,18 @@ def main(argv):
     ns = p.parse_args(argv)
     if ns.max_lines < 1:
         p.error("")
-    only = None
-    if ns.only is not None:
-        try:
-            only = {int(x) for x in ns.only.split(",")}
-        except ValueError:
-            p.error("")
+    only = parse_only(ns.only, p) if ns.only is not None else None
     wt = ns.worktree
     if git(wt, "rev-parse", "--git-dir") is None:
         raise Fail(2, "worktree: not a git worktree")
     spec = load_spec(ns.spec_id, ns.spec_json)
     fcs = spec["file_changes"]
-    if only is not None and not only <= set(range(1, len(fcs) + 1)):
-        raise Fail(2, "--only: index outside file_changes")
+    reads = spec.get("reads") or []
+    if only is not None:
+        if not {x for x in only if x[0] != "r"} <= {str(i) for i in range(1, len(fcs) + 1)}:
+            raise Fail(2, "--only: index outside file_changes")
+        if not {x for x in only if x[0] == "r"} <= {"r%d" % i for i in range(1, len(reads) + 1)}:
+            raise Fail(2, "--only: index outside reads")
     base = str(spec["base"])
     resolved = HEX.match(base) and git(wt, "rev-parse", "--verify", "--quiet", base + "^{commit}")
     tree = Tree(wt, base)
@@ -352,7 +443,9 @@ def main(argv):
                                  git(wt, "rev-parse", "--verify", "--quiet", ns.since + "^{commit}") is None):
         raise Fail(2, "--since: not a commit in this worktree")
     deleted_ok = {d["path"] for d in spec.get("deletes", [])}
-    anchors = [resolve(tree, i + 1, fc, deleted_ok, bool(resolved), listed) for i, fc in enumerate(fcs)]
+    anchors = [resolve(tree, str(i + 1), fc, deleted_ok, bool(resolved), listed) for i, fc in enumerate(fcs)]
+    anchors += [resolve(tree, "r%d" % (i + 1), {"location": rd["location"], "change": rd.get("why", "")},
+                        deleted_ok, bool(resolved), listed, read=True) for i, rd in enumerate(reads)]
 
     head = (git(wt, "rev-parse", "--short", "HEAD") or b"none").decode().strip()
     out = ["context-pack %s base %s HEAD %s modified %d" % (
@@ -361,29 +454,58 @@ def main(argv):
     out.append("")
     want = [a for a in anchors if a["window"] and (only is None or a["k"] in only)
             and (ns.since is None or overlaps_since(tree, ns.since, a))]
-    table_len = len(fcs)
-    skipped = []
-    left = ns.max_lines - len(out)
-    for idx, a in enumerate(want):
-        cap, body = window_body(tree, a)
-        full = len(body)
-        if only is None and full > WINDOW_CAP:
-            body = body[:WINDOW_CAP]
-        reserve = 1 if idx < len(want) - 1 or skipped else 0   # room for the not-expanded line
-        need = 1 + len(body) + (1 if len(body) < full else 0)
-        if only is not None and need > left - reserve and left - reserve >= 4:
-            body = body[:left - reserve - 2]
-            need = 1 + len(body) + 1
-        if need > left - reserve:
-            skipped.append(a["k"])
+    table_len = len(anchors)
+    def place(room):
+        """The windows that fit in room lines: (lines, skipped labels, room left, lines all would take)."""
+        lines, skipped, left, natural = [], [], room, 0
+        for idx, a in enumerate(want):
+            cap, body = window_body(tree, a)
+            full = len(body)
+            if only is None and full > WINDOW_CAP:
+                body = body[:WINDOW_CAP]
+            need = natural_need = 1 + len(body) + (1 if len(body) < full else 0)
+            reserve = 1 if idx < len(want) - 1 or skipped else 0   # room for the not-expanded line
+            if only is not None and need > left - reserve and left - reserve >= 4:
+                body = body[:left - reserve - 2]
+                need = 1 + len(body) + 1
+            natural += natural_need
+            if need > left - reserve:
+                skipped.append(a["k"])
+                continue
+            lines += [cap] + body
+            if len(body) < full:
+                lines.append("%d more lines: --only %s --max-lines %d" % (full - len(body), a["k"], table_len + full + 3))
+            left -= need
+        if skipped:
+            lines.append("not expanded: --only " + ",".join(skipped))
+            left -= 1
+        return lines, skipped, left, natural
+
+    windows = [(a["window"][1], a["window"][2], a["window"][3]) for a in anchors
+               if a["window"] and a["window"][0] == "wt"]
+    symbols = list(dict.fromkeys(a["symbol"] for a in want if a["symbol"]))
+    lists = [(sym, caller_list(wt, sym, windows)) for sym in symbols[:MAX_CALLER_SYMBOLS]]
+    unlisted = symbols[MAX_CALLER_SYMBOLS:]
+    list_total = sum(len(ls) for _, ls in lists) + (1 if unlisted else 0)
+    room = ns.max_lines - len(out)
+    lines, skipped, left, natural = place(room - list_total)
+    if skipped and lists:      # the lists lose: keep only the notes that name what is cut
+        lines, skipped, left, natural = place(room - (1 if lists else 0) - (1 if unlisted else 0))
+    elif lists:
+        left += list_total - (1 if unlisted else 0)
+    out += lines
+    cut = []
+    for sym, ls in lists:
+        if len(ls) > left:
+            cut.append((sym, len(ls)))
             continue
-        out.append(cap)
-        out += body
-        if len(body) < full:
-            out.append("%d more lines: --only %d --max-lines %d" % (full - len(body), a["k"], table_len + full + 3))
-        left -= need
-    if skipped:
-        out.append("not expanded: --only " + ",".join(map(str, skipped)))
+        out += ls
+        left -= len(ls)
+    if cut:
+        out.append("callers not printed: %s: --max-lines %d" % (
+            ",".join(c[0] for c in cut), table_len + 2 + natural + list_total))
+    if unlisted:
+        out.append("callers not listed: " + ",".join(unlisted))
     sys.stdout.reconfigure(encoding="utf-8", errors="replace", newline="\n")
     sys.stdout.write("\n".join(out) + "\n")
     return max([a["exit"] for a in anchors] or [0])

tools/fixtures/cargo-mutants-crate/.gitignore

@@ -0,0 +1,2 @@
+target/
+Cargo.lock

tools/fixtures/cargo-mutants-crate/Cargo.toml

@@ -0,0 +1,4 @@
+[package]
+name = "cmfix"
+version = "0.1.0"
+edition = "2021"

tools/fixtures/cargo-mutants-crate/src/alpha/mod.rs

@@ -0,0 +1,18 @@
+pub fn add(a: i32, b: i32) -> i32 {
+    a + b
+}
+
+/// Only tests/it.rs pins this one: a unit-filtered run cannot kill it.
+pub fn double(a: i32) -> i32 {
+    a * 2
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn add_adds() {
+        assert_eq!(add(2, 3), 5);
+    }
+}

tools/fixtures/cargo-mutants-crate/src/beta.rs

@@ -0,0 +1,18 @@
+pub fn neg(a: i32) -> i32 {
+    -a
+}
+
+/// No test pins this one anywhere: a real survivor in every run.
+pub fn unpinned(a: i32) -> i32 {
+    a + 1
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn neg_negates() {
+        assert_eq!(neg(4), -4);
+    }
+}

tools/fixtures/cargo-mutants-crate/src/lib.rs

@@ -0,0 +1,2 @@
+pub mod alpha;
+pub mod beta;

tools/fixtures/cargo-mutants-crate/tests/it.rs

@@ -0,0 +1,4 @@
+#[test]
+fn double_doubles() {
+    assert_eq!(cmfix::alpha::double(4), 8);
+}

tools/fixtures/context-pack/spec-reads.json

@@ -0,0 +1,17 @@
+{"id": {"id": "t:cut_spec:cut-x.r1", "kind": "CutSpec"},
+ "status": "InForce",
+ "document": {"kind": "cut_spec", "value": {
+  "base": "BASE", "deletes": [],
+  "file_changes": [
+   {"change": "symbol present in the moved window", "location": {"path": "a.txt", "line": 20, "end_line": 22, "symbol": "a21"}},
+   {"change": "symbol the window lacks", "location": {"path": "b.txt", "line": 30, "end_line": 31, "symbol": "b99"}},
+   {"change": "identifier with 3 callers outside the windows", "location": {"path": "sym.txt", "line": 4, "end_line": 5, "symbol": "needle_three"}},
+   {"change": "non-identifier symbol is a literal substring", "location": {"path": "sym.txt", "line": 9, "end_line": 9, "symbol": "::ba"}}
+  ],
+  "reads": [
+   {"why": "moved below the insertion", "location": {"path": "a.txt", "line": 20, "end_line": 22}},
+   {"why": "deleted path", "location": {"path": "c.txt", "line": 2, "end_line": 3, "symbol": "c9"}},
+   {"why": "path absent at base", "location": {"path": "sub/a.txt", "line": 1, "end_line": 2}},
+   {"why": "identifier with 60 callers", "location": {"path": "sym.txt", "line": 7, "end_line": 8, "symbol": "needle_many"}},
+   {"why": "an identifier matches whole words only", "location": {"path": "a.txt", "line": 20, "end_line": 22, "symbol": "a2"}}
+  ]}}}

tools/fixtures/mutation-mock/fakebin/cargo

@@ -0,0 +1,73 @@
+#!/usr/bin/env bash
+# Fake cargo for tools/test-tools.sh, only what tools/cargo-mutants.sh calls:
+#   cargo locate-project --workspace --message-format plain
+#   cargo test --no-run
+#   cargo test -- <filter> [<harness args>] --list      (prints "<n> tests, 0 benchmarks" per test binary)
+#   cargo mutants [--list] --in-diff <diff> [-f <file>] [-F <re>]... [--shard k/n] [-o <dir>] [...] [-- <filter> [-- <harness args>]]
+# FAKE_CM_TABLE: tab-separated  <mutant name> <outcome under a filtered run> <outcome under the full suite>
+#   (caught|missed|timeout|unviable). A run with -F is the full suite; a run with -f and a filter is filtered.
+# FAKE_CM_TESTS: tab-separated  <filter> <tests the filter selects>  (default 1)
+# FAKE_CM_RED=1|2: the stage-1 or stage-2 run fails its baseline (exit 4, no output).
+# FAKE_CM_KILLS: a path a run creates (the watchdog's YGG_KILLED flag appearing mid-job).
+# FAKE_CM_LOG: appended one line per run (stage, filter, harness args, open fds from 10 up).
+# FAKE_WSROOT: the workspace root relative to the repository root, with a trailing slash ('' = the repository root).
+case ${1:-} in
+  locate-project) echo "$(git rev-parse --show-toplevel)/${FAKE_WSROOT:-}Cargo.toml"; exit 0 ;;
+  test)
+    shift; for a; do [ "$a" != --no-run ] || exit 0; done
+    [ "${1:-}" = -- ] || { echo "fake cargo test: unsupported arguments" >&2; exit 64; }
+    shift; f=$1; shift; h=()
+    for a; do [ "$a" = --list ] || h+=("$a"); done
+    echo "count filter=$f harness=${h[*]}" >>"${FAKE_CM_LOG:?}"
+    n=$(awk -F'\t' -v f="$f" '$1 == f { print $2 }' "${FAKE_CM_TESTS:-/dev/null}")
+    printf '%s tests, 0 benchmarks\n0 tests, 0 benchmarks\n' "${n:-1}"; exit 0 ;;
+  mutants) shift ;;
+  *) echo "fake cargo: unsupported ${1:-}" >&2; exit 127 ;;
+esac
+list=0; mult=''; mintimeout=''; diff=''; ffile=''; res=(); shard=''; out=''; tail=()
+while [ $# -gt 0 ]; do
+  case $1 in
+    --list) list=1 ;;
+    --in-diff) diff=$2; shift ;;
+    -f) ffile=$2; shift ;;
+    -F) res+=("$2"); shift ;;
+    --shard) shard=$2; shift ;;
+    -o) out=$2; shift ;;
+    --jobs) shift ;;
+    --minimum-test-timeout) mintimeout=$2; shift ;;
+    --timeout-multiplier) mult=$2; shift ;;
+    --) shift; tail=("$@"); break ;;
+    *) echo "fake cargo mutants: unknown argument $1" >&2; exit 64 ;;
+  esac
+  shift
+done
+[ -n "$diff" ] && [ -f "$diff" ] || { echo "fake cargo mutants: no readable --in-diff" >&2; exit 64; }
+# the mutants of the files the diff touches (paths as the diff prints them: relative to the workspace root)
+touched=$(sed -n 's|^+++ b/||p' "$diff")
+sel=$(awk -F'\t' 'NR == FNR { t[$0] = 1; next } { f = $1; sub(/:.*/, "", f); if (f in t) print $1 "\t" $2 "\t" $3 }' <(printf '%s\n' "$touched") "${FAKE_CM_TABLE:?}")
+if [ -n "$ffile" ]; then sel=$(awk -F'\t' -v f="$ffile" '{ n = $1; sub(/:.*/, "", n); if (n == f) print }' <<<"$sel"); fi
+if [ "${#res[@]}" -gt 0 ]; then
+  keep=$(cut -f1 <<<"$sel" | perl -e '@r = map { qr/$_/ } @ARGV; while (<STDIN>) { chomp; for $r (@r) { if (/$r/) { print "$_\n"; last } } }' "${res[@]}")
+  sel=$(awk -F'\t' 'NR == FNR { k[$0] = 1; next } $1 in k' <(printf '%s\n' "$keep") <(printf '%s\n' "$sel"))
+fi
+if [ -n "$shard" ]; then
+  sel=$(awk -F'\t' -v k="${shard%/*}" -v n="${shard#*/}" '(NR - 1) % n == k' <<<"$sel")
+fi
+if [ "$list" = 1 ]; then cut -f1 <<<"$sel" | awk 'NF'; exit 0; fi
+stage=1; [ "${#res[@]}" -eq 0 ] || stage=2
+filter=''; harness=()
+if [ "${#tail[@]}" -gt 0 ] && [ "${tail[0]}" != -- ]; then filter=${tail[0]}; fi
+for i in "${!tail[@]}"; do if [ "${tail[$i]}" = -- ]; then harness=("${tail[@]:$((i + 1))}"); break; fi; done
+open=$(perl -MPOSIX -e '$n = 0; for (10 .. 40) { my $d = POSIX::dup($_); if (defined $d) { $n++; POSIX::close($d) } } print $n')
+[ -z "${FAKE_CM_KILLS:-}" ] || touch "$FAKE_CM_KILLS"   # a watchdog kill arriving while a run is going
+echo "stage=$stage filter=$filter harness=${harness[*]} openfds=$open mult=$mult min=$mintimeout" >>"${FAKE_CM_LOG:?}"
+[ "${FAKE_CM_RED:-}" != "$stage" ] || { echo "baseline failed" >&2; exit 4; }
+mkdir -p "$out/mutants.out/log"
+col=3; [ "$stage" = 2 ] || col=2
+for o in caught missed timeout unviable; do
+  awk -F'\t' -v c="$col" -v o="$o" '{ x = $c; if (x == o) print $1 }' <<<"$sel" >"$out/mutants.out/$o.txt"
+done
+# a run that selected no mutant (the awk above printed empty lines): drop them
+for o in caught missed timeout unviable; do sed -i '/^$/d' "$out/mutants.out/$o.txt"; done
+if [ -s "$out/mutants.out/timeout.txt" ]; then exit 3; elif [ -s "$out/mutants.out/missed.txt" ]; then exit 2; fi
+exit 0

tools/fixtures/mutation-mock/fakebin/docker

@@ -1,21 +1,22 @@
 #!/usr/bin/env bash
 # Mock docker for tools/test-tools.sh: a container is a directory, an image is a
 # copy of one, so `run` from a committed image really is copy-on-write. Implements
-# only what tools/mutation-table.sh --host calls: run, commit, cp, rm, rmi. The
-# in-container paths /mt and /seed map to the mounted host directories, and the
-# script's own /src and /tmp/mtm live inside the container directory.
+# only what tools/mutation-table.sh and tools/cargo-mutants.sh --host call: run, commit,
+# cp, rm, rmi. The in-container paths /mt, /cm, /out and /seed map to the mounted host
+# directories (/out is written through), and the script's own /src and /tmp/mtm live
+# inside the container directory.
 FD=${FAKE_DOCKER:?}; mkdir -p "$FD/c" "$FD/i"
 imgdir() { echo "$FD/i/${1//[:\/]/_}"; }
 cmd=$1; shift
 case $cmd in
   run)
-    rm_after=0; name=''; mt=''; seed=/nonexistent; labels=0; envs=()
+    rm_after=0; name=''; mt=''; cm=''; out=''; seed=/nonexistent; labels=0; envs=()
     while [ $# -gt 0 ]; do
       case $1 in
         --rm) rm_after=1 ;;
         --name) name=$2; shift ;;
         --label) labels=$((labels + 1)); shift ;;
-        -v) case $2 in *:/mt:ro) mt=${2%:/mt:ro} ;; *:/seed:ro) seed=${2%:/seed:ro} ;; esac; shift ;;
+        -v) case $2 in *:/mt:ro) mt=${2%:/mt:ro} ;; *:/cm:ro) cm=${2%:/cm:ro} ;; *:/out) out=${2%:/out} ;; *:/seed:ro) seed=${2%:/seed:ro} ;; esac; shift ;;
         -e) case $2 in BASH_ENV=*) ;; *) envs+=("$2") ;; esac; shift ;;
         -w) shift ;;
         --*=*) ;;
@@ -29,9 +30,9 @@ case $cmd in
     c=$FD/c/$name; rm -rf "$c"
     if [ -d "$(imgdir "$image")" ]; then cp -a "$(imgdir "$image")" "$c"; else mkdir -p "$c"; fi
     echo "run $name $image" >>"$FD/log"
-    script=${*: -1}; script=${script//\/mt\//$mt/}
+    script=${*: -1}; script=${script//\/mt\//$mt/}; script=${script//\/cm\//$cm/}
     ( for e in "${envs[@]}"; do export "$e"; done
-      export MT_SRC=$c/src MT_M=$c/tmp/mtm MT_DIR=$mt MT_SEED=$seed
+      export MT_SRC=$c/src MT_M=$c/tmp/mtm MT_DIR=$mt MT_SEED=$seed CM_SRC=$c/src CM_DIR=$cm CM_OUT=$out CM_SEED=$seed CM_TMP=$c/tmp
       bash -o pipefail -c "$script" )
     rc=$?
     [ "$rm_after" = 0 ] || rm -rf "$c"

tools/fixtures/mutation-mock/fakebin/flock

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+# Fake flock for tools/test-tools.sh (Git Bash has none): only `flock -n <fd>`, via perl's flock(2) on the inherited descriptor.
+[ "${1:-}" = -n ] && [ -n "${2:-}" ] || { echo "fake flock: unsupported arguments $*" >&2; exit 64; }
+exec perl -e 'use Fcntl qw(:flock); open(my $f, "+<&=", $ARGV[0]) or exit 2; exit(flock($f, LOCK_EX | LOCK_NB) ? 0 : 1)' "$2"

tools/mutation-table.sh

@@ -122,8 +122,8 @@ if [ "$1" = --host ]; then
   # Every container carries the job label (the stopgap's watchdog kills by it) and the same caps.
   common=(--label "$YGG_LABEL" "--cpus=${YGG_CPUS:-4}" "--memory=${YGG_MEM:-6g}"
     -v "$bundle:/mt:ro" -v /etc/machine-id:/etc/machine-id:ro
-    -v eureka-cargo-registry:/usr/local/cargo/registry -v eureka-nuget:/root/.nuget/packages -v eureka-sccache:/sccache
-    -e BASH_ENV=/tmp/.ygg-bash-env
+    -v eureka-cargo-home:/cargo-home -v eureka-nuget:/root/.nuget/packages -v eureka-sccache:/sccache
+    -e BASH_ENV=/tmp/.ygg-bash-env -e CARGO_HOME=/cargo-home
     -e "WORKDIR=${WORKDIR:-.}" -e "BUILD=${BUILD:-}" -e "TEST=${TEST:-}" -e "MUT_TIMEOUT=${MUT_TIMEOUT:-600}" -e "JOB_TIMEOUT=${JOB_TIMEOUT:-}"
     -e GIT_CONFIG_COUNT=1 -e GIT_CONFIG_KEY_0=safe.directory -e 'GIT_CONFIG_VALUE_0=*')
   [ -z "${YGG_NONCE:-}" ] || common+=(-e "YGG_NONCE=$YGG_NONCE")

tools/stopgap/ygg-verify.sh

@@ -20,7 +20,7 @@
 #      the commit out detached. It is a real clone, not a worktree, because a
 #      worktree's .git file points at a host path the container cannot see.
 #   3. Runs <command> in <image> under a CPU and memory cap, niced. Each
-#      toolchain gets one shared registry cache. The build output directory
+#      toolchain gets one shared cargo home (registry and package-cache lock). The build output directory
 #      stays inside the work directory and is never shared between checkouts.
 #      CARGO_TARGET_DIR is deliberately NOT set: cargo's default (<workspace>/
 #      target) is already inside /src, and forcing it made cargo-mutants' --jobs
@@ -83,10 +83,12 @@
 #   YGG_WORK (the clone), YGG_IMAGE, YGG_CPUS, YGG_MEM, YGG_CNAME (job name),
 #   YGG_LABEL (every container it starts must carry `--label $YGG_LABEL`: the
 #   watchdog kills containers by that label), YGG_KILLED (a path that exists once
-#   the watchdog has killed the job: stop starting work) and DOCKER_ARGS. The
-#   command owns the container topology and must remove what it creates.
-#   tools/mutation-table.sh is the one user: it snapshots a baselined container
-#   and runs each mutant in a fresh container from the snapshot.
+#   the watchdog has killed the job: stop starting work), YGG_SLOTS and YGG_ROOT
+#   (the slot pool: $YGG_ROOT/slot-<i>.lock for i in 1..$YGG_SLOTS, flock -n) and
+#   DOCKER_ARGS. The command owns the container topology and must remove what it
+#   creates. Two users: tools/mutation-table.sh snapshots a baselined container
+#   and runs each mutant in a fresh container from the snapshot;
+#   tools/cargo-mutants.sh also leases free slot locks for extra containers.
 #   DOCKER_ARGS='<extra docker run flags>' passes through to the container's
 #   own `docker run`, appended after the fixed flags and before the image name
 #   (e.g. DOCKER_ARGS='--sysctl net.ipv6.conf.all.disable_ipv6=0' or
@@ -133,8 +135,8 @@
 #           dotnet tool install -g dotnet-stryker)
 #   any other value is used as an image name as-is.
 # Example:
-#   ygg-verify.sh /f/Projects/Huginn HEAD rust \
-#     'cargo test --workspace && git diff BASE HEAD > /tmp/d && cargo mutants --in-diff /tmp/d'
+#   ygg-verify.sh /f/Projects/Huginn HEAD rust 'cargo test --workspace'
+# Rust mutation runs use tools/cargo-mutants.sh, never an inline cargo mutants command.
 set -euo pipefail
 
 here=$(cd "$(dirname "$0")" && pwd)
@@ -186,7 +188,6 @@ ygg_summarize() {
     if [ "$untrusted" -gt 0 ]; then
       echo "$untrusted YGG-SUMMARY lines without this run's nonce were ignored (a test printed them, or the table printer predates the nonce); see the log"
     fi
-    { grep -E '^(MISSED|TIMEOUT) |mutants tested' "$log" || true; } | awk 'NR<=20'
     if [ "$status" != 0 ]; then
       if [ "$nf" -eq 0 ] && [ "$f" -eq 0 ] && [ "$own" -eq 0 ] && [ -z "$loads" ]; then
         echo "exit non-zero with no failing test parsed: build error, crash, timeout or a non-test command"
@@ -389,7 +390,7 @@ if [ "$host_mode" = 1 ]; then
   # Own process group (set -m), started in the job's work directory, so the watchdog can signal all of it.
   set -m
   ( cd "$work" && export YGG_WORK=$work YGG_IMAGE=$image YGG_CPUS=$cpus YGG_MEM=$mem YGG_CNAME=$cname YGG_LABEL=$label \
-      YGG_KILLED=$killed DOCKER_ARGS=$docker_args
+      YGG_KILLED=$killed YGG_SLOTS=$slots YGG_ROOT=$root DOCKER_ARGS=$docker_args
     [ -z "$nonce" ] || export YGG_NONCE=$nonce
     exec bash -o pipefail -c "$cmd" ) </dev/null &
   hostpid=$!
@@ -401,14 +402,20 @@ if [ "$host_mode" = 1 ]; then
   # command's status comes from the host command, not from a killed container).
   if [ -e "$killed" ]; then status=124; fi
 else
-sudo nice -n 10 docker run --rm --name "$cname" --label "$label" --cpus="$cpus" --memory="$mem" \
+# Priority is set inside the container: nice on the docker client does not reach a process
+# containerd starts. Jobs run at nice 10 and idle IO class, so the swarm's daemons and turns
+# on the same disk go first (2026-10-31: three verify jobs held IO pressure at ~75% full).
+# Cargo's package-cache lock lives in $CARGO_HOME, so the shared volume is CARGO_HOME itself: a registry-only mount left the
+# lock in each container's layer and sibling containers unpacking one crate removed each other's directories (2026-11-03).
+sudo docker run --rm --name "$cname" --label "$label" --cpus="$cpus" --memory="$mem" \
   -v "$work:/src" -v /etc/machine-id:/etc/machine-id:ro \
-  -v eureka-cargo-registry:/usr/local/cargo/registry -v eureka-nuget:/root/.nuget/packages \
-  -v eureka-sccache:/sccache \
+  -v eureka-cargo-home:/cargo-home -v eureka-nuget:/root/.nuget/packages \
+  -v eureka-sccache:/sccache -e CARGO_HOME=/cargo-home \
   -e BASH_ENV=/tmp/.ygg-bash-env ${nonce:+-e YGG_NONCE=$nonce} \
   -e GIT_CONFIG_COUNT=1 -e GIT_CONFIG_KEY_0=safe.directory -e GIT_CONFIG_VALUE_0='*' \
   $docker_args \
-  -w /src "$image" bash -o pipefail -c "printf 'set -o pipefail\n' >/tmp/.ygg-bash-env; $cmd"
+  -w /src "$image" sh -c 'if command -v ionice >/dev/null 2>&1; then exec nice -n 10 ionice -c3 "$@"; else exec nice -n 10 "$@"; fi' sh \
+  bash -o pipefail -c "printf 'set -o pipefail\n' >/tmp/.ygg-bash-env; $cmd"
 status=$?
 fi
 set -e

tools/test-tools.sh

@@ -5,6 +5,9 @@
 # reproducer) are real Yggdrasil runs, 2026-10-01; soul-s5/*.log are real
 # dotnet, pytest, vitest and cargo runs of Soul's probe repo (several runs per
 # log, split by "=== MARK <name>" lines); the rest are hand-written.
+# The mutation runners tools/mutation-table.sh and tools/cargo-mutants.sh (launcher, host driver
+# and container halves) run under a mock docker and, for cargo-mutants, a fake cargo and flock
+# (fixtures/mutation-mock/fakebin), with real slot locks.
 # Run: bash tools/test-tools.sh   (no network, no builds)
 set -uo pipefail
 here=$(cd "$(dirname "$0")" && pwd)
@@ -192,6 +195,210 @@ check "$(seg jest-real.log exit)" 1 "exit non-zero with no failing test parsed"
 # F4: the "nothing recognised" line names every framework the parser reads
 check "$(seg jest-real.log exit)" 1 "no test counts recognised in the log (cargo, dotnet, vitest, jest, pytest)"
 
+# ---- tools/cargo-mutants.sh: the launcher, host driver and container halves, through the mock docker
+# and fixtures/mutation-mock/fakebin/cargo (a fake `cargo mutants` driven by a table of mutant ->
+# outcome under a filtered run and under the full suite). The launcher runs for real: its bundle,
+# quoting and the environment it hands the driver are the production path; only ygg-verify.sh is
+# stubbed, by a script that does what RUN_ON_HOST=1 does (run the command inside the checked-out
+# revision). Slot locks are real flock(2) locks on files, taken by the driver and by the test.
+CMB=$here/fixtures/mutation-mock/fakebin
+cmrepo() {   # cmrepo A|B|C: sets cm_repo and cm_wd. A: a workspace at the repo root, workdir crates/x. B: a standalone package pkg/ under the repo root. C: B touching only the two files that have tests.
+  local r f c; r=$(mktemp -d); cm_repo=$r/repo; mkdir -p "$cm_repo"; git -C "$cm_repo" init -q
+  c="git -C $cm_repo -c user.name=t -c user.email=t@t"
+  if [ "$1" = A ]; then
+    cm_wd=crates/x; mkdir -p "$cm_repo/crates/x/src/alpha" "$cm_repo/crates/x/src/bin"
+    printf '[workspace]\nmembers = ["crates/x"]\n' >"$cm_repo/Cargo.toml"; printf '[package]\nname = "x"\n' >"$cm_repo/crates/x/Cargo.toml"
+    : >"$cm_repo/crates/x/src/lib.rs"; $c add -A 2>/dev/null; $c commit -qm c1
+    for f in src/lib.rs src/main.rs src/gamma.rs src/beta.rs src/alpha/mod.rs src/alpha/inner.rs src/bin/tool.rs build.rs; do echo "// $f" >"$cm_repo/crates/x/$f"; done
+  else
+    cm_wd=pkg; mkdir -p "$cm_repo/pkg/src/a" "$cm_repo/pkg/src/bin"
+    printf '[package]\nname = "p"\n' >"$cm_repo/pkg/Cargo.toml"; : >"$cm_repo/pkg/src/lib.rs"; $c add -A 2>/dev/null; $c commit -qm c1
+    for f in src/a/mod.rs src/a/b.rs; do echo "// $f" >"$cm_repo/pkg/$f"; done
+    [ "$1" = C ] || for f in src/lib.rs src/main.rs src/bin/x.rs build.rs; do echo "// $f" >"$cm_repo/pkg/$f"; done
+  fi
+  $c add -A 2>/dev/null; $c commit -qm c2
+}
+cmtable() {   # cmtable A|B|C: sets cm_table (name <TAB> outcome under a filtered run <TAB> outcome under the full suite)
+  cm_table=$(mktemp)
+  if [ "$1" = A ]; then
+    local p=crates/x/src
+    printf '%s\n' \
+      "$p/alpha/mod.rs:2:5: replace add -> i32 with 0	caught	caught" \
+      "$p/alpha/mod.rs:7:7: replace * with + in double	missed	caught" \
+      "$p/alpha/mod.rs:9:9: replace && with || in check	missed	missed" \
+      "$p/alpha/mod.rs:12:5: replace f(x) -> Vec<i32> with vec![1]	caught	caught" \
+      "$p/alpha/mod.rs:15:5: replace id -> Option<i32> with None	unviable	unviable" \
+      "$p/alpha/inner.rs:3:5: replace slow -> u32 with 0	timeout	caught" \
+      "$p/alpha/inner.rs:6:5: replace spin -> u32 with 1	missed	timeout" \
+      "$p/beta.rs:2:5: replace b1 -> i32 with 0	missed	caught" \
+      "$p/beta.rs:3:5: replace b2 -> i32 with 0	missed	missed" \
+      "$p/beta.rs:4:5: replace b3 -> i32 with 0	missed	unviable" \
+      "$p/gamma.rs:2:5: replace g -> i32 with 0	caught	caught" \
+      "$p/lib.rs:2:5: replace l1 -> i32 with 0	missed	caught" \
+      "$p/lib.rs:3:5: replace f(x) -> Vec<i32> with vec![1]	missed	missed" \
+      "$p/main.rs:2:5: replace m -> i32 with 0	missed	caught" \
+      "crates/x/build.rs:2:5: replace bu -> i32 with 0	missed	caught" \
+      "$p/bin/tool.rs:2:5: replace t -> i32 with 0	missed	caught" >"$cm_table"
+  elif [ "$1" = C ]; then
+    printf '%s\n' "src/a/mod.rs:2:5: replace a -> i32 with 0	caught	caught" "src/a/b.rs:2:5: replace a -> i32 with 0	caught	caught" >"$cm_table"
+  else
+    printf '%s\n' "src/lib.rs:2:5: replace a -> i32 with 0	caught	caught" "src/main.rs:2:5: replace a -> i32 with 0	caught	caught" \
+      "src/bin/x.rs:2:5: replace a -> i32 with 0	caught	caught" "build.rs:2:5: replace a -> i32 with 0	caught	caught" \
+      "src/a/mod.rs:2:5: replace a -> i32 with 0	caught	caught" "src/a/b.rs:2:5: replace a -> i32 with 0	caught	caught" >"$cm_table"
+  fi
+}
+# cm <A|B> [VAR=value]...: runs the launcher; sets cm_out, cm_rc, cm_root, cm_fd, cm_log. HOLD_OWN=1 holds the job's own slot as
+# ygg-verify does (a descriptor the driver inherits); HOLD_OTHERS=<n> holds n further slots as other jobs would (separate processes); PSI=<n> is the io pressure file's full avg60.
+cm() {
+  local lay=$1; shift
+  cmrepo "$lay"; cmtable "$lay"
+  cm_root=$(dirname "$cm_repo"); cm_fd=$cm_root/fd; cm_log=$cm_root/cargo.log
+  mkdir -p "$cm_fd" "$cm_root/tools/stopgap" "$cm_root/ygg" "$cm_root/tmp"
+  cp "$here/cargo-mutants.sh" "$cm_root/tools/"
+  printf '#!/usr/bin/env bash\n# test stub of ygg-verify.sh RUN_ON_HOST=1: <repo> <rev> <image> <cmd>; runs cmd as the host half inside the revision\ncd "$YGG_WORK" && exec bash -o pipefail -c "$4"\n' >"$cm_root/tools/stopgap/ygg-verify.sh"
+  local holders=() i n own=0 others=0 psi=0.00 kv env=()
+  for kv in "$@"; do case $kv in HOLD_OWN=*) own=${kv#*=} ;; HOLD_OTHERS=*) others=${kv#*=} ;; PSI=*) psi=${kv#*=} ;; *) env+=("$kv") ;; esac; done
+  for i in $(seq 1 "$others"); do
+    perl -e 'use Fcntl ":flock"; open(F, ">>", $ARGV[0]) or die; flock(F, LOCK_EX) or die; open(R, ">", "$ARGV[0].ready"); close R; sleep 120' "$cm_root/ygg/slot-$((i + 1)).lock" & holders+=($!)
+    for n in $(seq 1 50); do [ -e "$cm_root/ygg/slot-$((i + 1)).lock.ready" ] && break; sleep 0.1; done
+  done
+  cm_out=$( ( if [ "$own" = 1 ]; then exec {ownfd}>"$cm_root/ygg/slot-1.lock"; PATH=$CMB:$PATH flock -n "$ownfd"; fi
+      export PATH=$CMB:$PATH FAKE_DOCKER=$cm_fd FAKE_CM_TABLE=$cm_table FAKE_CM_LOG=$cm_log FAKE_CM_TESTS=$cm_root/tests.tsv \
+        FAKE_WSROOT=$([ "$lay" = A ] || echo pkg/) YGG_WORK=$cm_repo YGG_IMAGE=rust YGG_CNAME=job1 YGG_LABEL=eureka-verify-job=job1 YGG_CPUS=1 YGG_MEM=1g \
+        YGG_SLOTS=5 YGG_ROOT=$cm_root/ygg YGG_NONCE=n0nce1 CM_PSI=$cm_root/psi TMPDIR=$cm_root/tmp
+      printf 'beta::\t0\n' >"$cm_root/tests.tsv"
+      printf 'some avg10=0.00 avg60=0.00 avg300=0.00 total=0\nfull avg10=0.00 avg60=%s avg300=0.00 total=0\n' "$psi" >"$cm_root/psi"
+      for kv in "${env[@]}"; do export "${kv?}"; done
+      timeout 240 bash "$cm_root/tools/cargo-mutants.sh" "$cm_repo" HEAD HEAD~1 "$cm_wd" 2>&1 ) )
+  cm_rc=$?
+  for i in "${holders[@]}"; do kill "$i" 2>/dev/null; done; wait 2>/dev/null
+}
+cmcheck() {  # cmcheck <name> <must-contain | !must-not-contain>...
+  local name=$1 s; shift
+  for s in "$@"; do
+    case $s in
+      '!'*) if printf '%s\n' "$cm_out" | grep -qF -- "${s#!}"; then echo "FAIL cargo-mutants $name: must not contain: ${s#!}"; printf '%s\n' "$cm_out" | tail -n 12; fail=1; return; fi ;;
+      *) printf '%s\n' "$cm_out" | grep -qF -- "$s" || { echo "FAIL cargo-mutants $name: missing: $s"; printf '%s\n' "$cm_out" | tail -n 14; fail=1; return; } ;;
+    esac
+  done
+  echo "ok   cargo-mutants $name"
+}
+cmrc() { [ "$cm_rc" = "$2" ] || { echo "FAIL cargo-mutants $1: exit $cm_rc, want $2"; printf '%s\n' "$cm_out" | tail -n 8; fail=1; }; }
+cmclean() {   # nothing the job made may outlive it: no container directory, no bundle, no staging directory
+  local left; left=$(ls "$cm_fd/c" "$cm_root/tmp" 2>/dev/null | grep -v '^$' | grep -v ':$' | paste -sd, -)
+  if [ -z "$left" ]; then echo "ok   cargo-mutants $1: containers, bundle and staging removed"; else echo "FAIL cargo-mutants $1: left behind: $left"; fail=1; fi
+}
+cmlocks() {   # cmlocks <case>: after the driver exits, every slot lock can be taken again by a fresh process
+  local i bad=''
+  for i in 1 2 3 4 5; do bash -c "exec {fd}>'$cm_root/ygg/slot-$i.lock'; PATH=$CMB:\$PATH flock -n \$fd" || bad="$bad $i"; done
+  if [ -z "$bad" ]; then echo "ok   cargo-mutants $1: every slot lock is free again"; else echo "FAIL cargo-mutants $1: slots still locked:$bad"; fail=1; fi
+}
+
+# filter derivation, stage-1 survivors and timeouts confirmed, zero-test filter, no raw stage-1 lines, exit 2 and 3 normal
+cm A TEST_ARGS='--skip flaky'
+cmrc A 0
+cmcheck A-filters \
+  'FILTER crates/x/src/alpha/mod.rs alpha:: tests=1 mutants=5' 'FILTER crates/x/src/alpha/inner.rs alpha::inner:: tests=1 mutants=2' \
+  'FILTER crates/x/src/gamma.rs gamma:: tests=1 mutants=1' \
+  '!FILTER crates/x/src/lib.rs' '!FILTER crates/x/src/main.rs' '!FILTER crates/x/src/bin/tool.rs' '!FILTER crates/x/build.rs'
+cmcheck A-zero-test-filter 'FILTER crates/x/src/beta.rs beta:: tests=0 mutants=3' 'caught=10 missed=3 timeout=1 unviable=2'
+cmcheck A-confirmed-and-counted 'MUTANTS tested=16 caught=10 missed=3 timeout=1 unviable=2 | stage1 filtered=8 survivors=4 confirmed_caught=2 | containers=3 |' \
+  '!replace * with + in double' '!replace slow -> u32 with 0' '!replace add -> i32' \
+  'MISSED crates/x/src/alpha/mod.rs:9:9: replace && with || in check' 'MISSED crates/x/src/beta.rs:3:5: replace b2' 'MISSED crates/x/src/lib.rs:3:5: replace f(x) -> Vec<i32> with vec![1]' \
+  'TIMEOUT crates/x/src/alpha/inner.rs:6:5: replace spin'
+if [ "$(printf '%s\n' "$cm_out" | grep -c "^YGG-SUMMARY/n0nce1: MISSED ")" = 3 ]; then echo "ok   cargo-mutants A-missed-once: 3 final MISSED lines"; else echo "FAIL cargo-mutants A-missed-once"; fail=1; fi
+if printf '%s\n' "$cm_out" | grep -qE '^(MISSED|TIMEOUT) '; then echo "FAIL cargo-mutants A-no-raw-lines: a MISSED or TIMEOUT line outside the nonce-tagged lines"; fail=1; else echo "ok   cargo-mutants A-no-raw-lines"; fi
+if grep -qF 'stage=1 filter=alpha:: harness=--skip flaky' "$cm_log" && grep -qF 'stage=1 filter=alpha::inner:: harness=--skip flaky' "$cm_log" && grep -qF 'stage=2 filter= harness=--skip flaky' "$cm_log"
+then echo "ok   cargo-mutants A-harness-args: TEST_ARGS follow the filter in stage 1 and stand alone in stage 2"; else echo "FAIL cargo-mutants A-harness-args"; sort -u "$cm_log"; fail=1; fi
+if [ "$(grep -c '^stage=2' "$cm_log")" = 3 ]; then echo "ok   cargo-mutants A-stage2-sharded: 3 full-suite shards"; else echo "FAIL cargo-mutants A-stage2-sharded"; fail=1; fi
+# a file whose filter selects 0 tests is found at plan time and never pays a stage-1 pass; its names run in stage 2
+if grep -qF 'count filter=beta:: harness=--skip flaky' "$cm_log" && ! grep -q '^stage=1 filter=beta::' "$cm_log"
+then echo "ok   cargo-mutants A-zero-test-plan: counted at plan time, no stage-1 run for it"; else echo "FAIL cargo-mutants A-zero-test-plan"; sort -u "$cm_log"; fail=1; fi
+# the stage-2 timeout bound is the generous default with a floor, not a tight multiple of a quiet-host baseline
+if [ "$(grep -c '^stage=2 .* mult=5 min=20$' "$cm_log")" = 3 ] && ! grep '^stage=2' "$cm_log" | grep -qv 'mult=5 min=20$'
+then echo "ok   cargo-mutants A-timeout-bound: stage 2 runs at 5x with a 20 s floor"; else echo "FAIL cargo-mutants A-timeout-bound"; grep '^stage=2' "$cm_log"; fail=1; fi
+cmclean A; cmlocks A
+
+# derivation on a standalone package under the repo root: the diff is taken at the workspace root (--relative)
+cm B
+cmrc B 0
+cmcheck B-derivation 'FILTER src/a/mod.rs a:: tests=1 mutants=1' 'FILTER src/a/b.rs a::b:: tests=1 mutants=1' \
+  '!FILTER src/lib.rs' '!FILTER src/main.rs' '!FILTER src/bin/x.rs' '!FILTER build.rs' 'MUTANTS tested=6 caught=6 missed=0'
+# FILTERS overrides the derived filter; '-' forces the full suite
+cm B 'FILTERS=src/a/b.rs=-,src/lib.rs=special::'
+cmcheck B-override 'FILTER src/lib.rs special:: tests=1 mutants=1' 'FILTER src/a/mod.rs a:: ' '!FILTER src/a/b.rs' 'tested=6 caught=6'
+
+# stage 1 settles every mutant: the full-suite baseline still runs (stage 2 is never skipped), and a red one is a red job
+cm C
+cmrc C-settled 0
+cmcheck C-settled 'MUTANTS tested=2 caught=2 missed=0 timeout=0 unviable=0 | stage1 filtered=2 survivors=0 confirmed_caught=0'
+if [ "$(grep -c '^stage=2' "$cm_log")" = 1 ]; then echo "ok   cargo-mutants C-baseline-runs: one full-suite run although stage 1 settled every mutant"; else echo "FAIL cargo-mutants C-baseline-runs"; sort -u "$cm_log"; fail=1; fi
+cm C FAKE_CM_RED=2
+[ "$cm_rc" != 0 ] || { echo "FAIL cargo-mutants C-red-baseline: exit 0"; fail=1; }
+cmcheck C-red-baseline 'ERROR stage 2 (shard 1 of 1)' 'container exited 4' '!MUTANTS'
+cmclean C-red-baseline
+# CONFIRM_TIMEOUT_MULT and MIN_TEST_TIMEOUT reach the stage-2 run
+cm A CONFIRM_TIMEOUT_MULT=9 MIN_TEST_TIMEOUT=33
+if grep '^stage=2' "$cm_log" | grep -q 'mult=9 min=33$' && ! grep '^stage=2' "$cm_log" | grep -qv 'mult=9 min=33$'; then echo "ok   cargo-mutants timeout-overrides: 9x with a 33 s floor in stage 2"; else echo "FAIL cargo-mutants timeout-overrides"; grep '^stage=2' "$cm_log"; fail=1; fi
+# slot lease: the job's own slot is held by ygg-verify (an inherited descriptor), others by other jobs
+cm A HOLD_OWN=1 HOLD_OTHERS=1; cmcheck lease-free 'containers=3 |'; cmlocks lease-free
+cm A HOLD_OWN=1 HOLD_OTHERS=3; cmcheck lease-one-free 'containers=2 |'
+cm A HOLD_OWN=1 HOLD_OTHERS=4; cmcheck lease-none-free 'containers=1 |' 'tested=16'; cmlocks lease-none-free
+open_none=$(grep -o 'openfds=[0-9]*' "$cm_log" | sort -u | paste -sd, -)
+cm A HOLD_OWN=1 HOLD_OTHERS=1; open_leased=$(grep -o 'openfds=[0-9]*' "$cm_log" | sort -u | paste -sd, -)
+if [ "$open_none" = "$open_leased" ]; then echo "ok   cargo-mutants lease-not-inherited: containers see the same descriptors with 2 leases held as with none ($open_none)"; else echo "FAIL cargo-mutants lease-not-inherited: $open_none vs $open_leased"; fail=1; fi
+cm A PSI=41.00; cmcheck lease-io-pressure 'containers=1 |' 'tested=16'
+# a red baseline, in stage 1 or in stage 2, is not a clean run
+cm A FAKE_CM_RED=1
+[ "$cm_rc" != 0 ] || { echo "FAIL cargo-mutants red-stage1: exit 0"; fail=1; }
+cmcheck red-stage1 'ERROR stage 1 (' 'container exited 4' '!MUTANTS' '!MISSED' '!TIMEOUT'
+cm A FAKE_CM_RED=2
+[ "$cm_rc" != 0 ] || { echo "FAIL cargo-mutants red-stage2: exit 0"; fail=1; }
+cmcheck red-stage2 'ERROR stage 2 (shard' 'container exited 4' '!MUTANTS' '!MISSED' '!TIMEOUT'
+cmclean red-stage2
+# NAMES rerun: no stage-1 container, only the listed names, on the full suite
+cm_names=$(mktemp)
+printf '%s\n' 'crates/x/src/alpha/mod.rs:9:9: replace && with || in check' 'crates/x/src/lib.rs:3:5: replace f(x) -> Vec<i32> with vec![1]' 'crates/x/src/beta.rs:2:5: replace b1 -> i32 with 0' >"$cm_names"
+cm A "NAMES=$cm_names"
+cmrc names 0
+cmcheck names 'MUTANTS tested=3 caught=1 missed=2 timeout=0 unviable=0 | stage1 filtered=0 survivors=0 confirmed_caught=0' 'MISSED crates/x/src/alpha/mod.rs:9:9' '!FILTER'
+if grep -q 'run job1-s1' "$cm_fd/log" || grep -q '^stage=1' "$cm_log"; then echo "FAIL cargo-mutants names: a stage-1 container or a filtered run"; fail=1; else echo "ok   cargo-mutants names: no stage-1 container"; fi
+# a name the range does not produce is an error that does not echo the name
+printf '%s\n' 'crates/x/src/lib.rs:99:9: replace no_such_secret_name -> i32 with 0' >"$cm_names"
+cm A "NAMES=$cm_names"
+[ "$cm_rc" != 0 ] || { echo "FAIL cargo-mutants names-unknown: exit 0"; fail=1; }
+cmcheck names-unknown 'ERROR 1 mutants selected' '!no_such_secret_name' '!MUTANTS'
+rm -f "$cm_names"
+# killed: a job the watchdog already killed starts nothing and leaves nothing
+cm_k=$(mktemp); cm A "YGG_KILLED=$cm_k"; rm -f "$cm_k"
+cmrc killed-before 124
+if grep -q '^run ' "$cm_fd/log" 2>/dev/null; then echo "FAIL cargo-mutants killed-before: a container started"; fail=1; else echo "ok   cargo-mutants killed-before: no container started"; fi
+cmclean killed-before
+# the flag appears while stage 1 runs: stage 2 never starts
+cm_k=$(mktemp -u); cm A "YGG_KILLED=$cm_k" "FAKE_CM_KILLS=$cm_k"; rm -f "$cm_k"
+cmrc killed-during 124
+cmcheck killed-during 'JOB KILLED' '!MUTANTS'
+if grep -q 'run job1-s2' "$cm_fd/log"; then echo "FAIL cargo-mutants killed-during: a stage-2 container started"; fail=1; else echo "ok   cargo-mutants killed-during: no stage-2 container"; fi
+cmclean killed-during
+# the launcher refuses bad input before any job starts, and never echoes the value it refused
+cmrepo A
+for v in 'SHARDS=0' 'SHARDS=x;SECRET' 'FILTERS=nopairSECRET' 'CONFIRM_TIMEOUT_MULT=2;SECRET'; do
+  lo=$(env "$v" bash "$here/cargo-mutants.sh" "$cm_repo" HEAD HEAD~1 "$cm_wd" 2>&1); lrc=$?
+  if [ "$lrc" = 2 ] && ! printf '%s' "$lo" | grep -q SECRET; then echo "ok   cargo-mutants launcher refuses ${v%%=*}"; else echo "FAIL cargo-mutants launcher ${v%%=*}: exit $lrc, output: $lo"; fail=1; fi
+done
+lo=$(bash "$here/cargo-mutants.sh" "$cm_repo" HEAD~1 HEAD "$cm_wd" 2>&1); lrc=$?
+if [ "$lrc" = 2 ] && printf '%s' "$lo" | grep -q 'not an ancestor'; then echo "ok   cargo-mutants launcher refuses a base that is not an ancestor"; else echo "FAIL cargo-mutants launcher base: exit $lrc, output: $lo"; fail=1; fi
+
+# the -F escaper: every regex metacharacter, the pipe included, is escaped; nothing else is touched
+esc_bad=''
+for c in '\' . + '*' '?' '(' ')' '|' '[' ']' '{' '}' '^' '$'; do
+  got=$(printf 'a%sb\n' "$c" | bash "$here/cargo-mutants.sh" --escape)
+  [ "$got" = '^a'\\"$c"'b$' ] || esc_bad="$esc_bad [$c]"
+done
+got=$(printf 'replace x -> Vec<i32> with vec![1] & 2 - 3 #\n' | bash "$here/cargo-mutants.sh" --escape)
+[ "$got" = '^replace x -> Vec<i32> with vec!\[1\] & 2 - 3 #$' ] || esc_bad="$esc_bad [plain]"
+if [ -z "$esc_bad" ]; then echo "ok   cargo-mutants escaper: all 14 metacharacters escaped, others literal"; else echo "FAIL cargo-mutants escaper:$esc_bad"; fail=1; fi
+
 # wait-on.sh: pid, log and file forms, and the vanished-process exit
 W=$here/wait-on.sh
 wo() { local rc; WAIT_MAX=${WM:-4} bash "$W" "$@" >"$T/wo.out" 2>&1; rc=$?; echo "$rc"; }
@@ -236,6 +443,15 @@ seqf() { local i; for i in $(seq 1 "$2"); do echo "$1$i"; done; }
 g init -q
 seqf a 40 >"$R/a.txt"; seqf b 40 >"$R/b.txt"; seqf c 10 >"$R/c.txt"; seqf d 20 >"$R/d.txt"
 seqf e 10 >"$R/e.txt"; seqf f 20 >"$R/f.txt"; seqf g 300 >"$R/big.txt"; seqf h 5 | sed 's/$/
/' >"$R/h.txt"; seqf m 40 >"$R/m.txt"
+printf 's1\ns2\ns3\ns4\ndef needle_three\ns6\ns7 needle_many\ns8\nfoo::bar\ns10\n' >"$R/sym.txt"
+printf 'needle_three call 1\nneedle_three call 2\nneedle_three call 3\nneedle_threefold is another word\n' >"$R/zcallers.txt"
+echo 'bound_fifty bound_fiftyone spread_sym long_symbol q.zq sym_bad twenty_sym' >"$R/anchors.txt"
+seqf "bound_fifty x" 50 >"$R/bound50.txt"; seqf "bound_fiftyone x" 51 >"$R/bound51.txt"; seqf "q.zq x" 51 >"$R/dotted.txt"
+printf 'long_symbol %s%s\r' "$(printf '%0150d' 0 | tr 0 z)" "$(printf '%0100d' 0 | tr 0 y)" >"$R/longline.txt"; printf '\n' >>"$R/longline.txt"
+printf 'sym_bad \377 endX\r\n' >"$R/bad.txt"
+mkdir -p "$R/manyf"; for i in $(seq -w 1 21); do seqf "spread_sym $i-" 3 >"$R/manyf/f$i.txt"; done; echo "spread_sym extra" >>"$R/manyf/f21.txt"
+mkdir -p "$R/twf"; for i in $(seq -w 1 20); do seqf "twenty_sym $i-" 3 >"$R/twf/f$i.txt"; done
+seqf "needle_many x." 30 >"$R/many1.txt"; seqf "needle_many y." 30 >"$R/many2.txt"
 g add -A; g commit -q -m base; BASE=$(git -C "$R" rev-parse HEAD)
 { sed -n 1,5p "$R/a.txt"; printf 'ins1\nins2\nins3\n'; sed -n '6,$p' "$R/a.txt"; } >"$R/a.new"; mv "$R/a.new" "$R/a.txt"
 sed -e '2,3d' -e 's/^b10$/b10-EDITED/' "$R/b.txt" >"$R/b.new"; mv "$R/b.new" "$R/b.txt"
@@ -337,6 +553,124 @@ cin "window cut at 100 lines" "56 more lines: --only 1 --max-lines 160"
 r=$(cpo --spec-json "$S1" --only 1 --max-lines 160); cchk "--only with the suggested --max-lines" 0 "$r"
 cnot "full window needs no more-lines note" "more lines"
 [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 160 ] && echo "ok   context-pack suggested --max-lines is exact" || { echo "FAIL context-pack suggested max: $(wc -l <"$T/cp.out")"; fail=1; }
+# reads, symbols and caller lists
+sed "s/\"BASE\"/\"$BASE\"/" "$CF/spec-reads.json" >"$T/cp-spec-reads.json"; SR=$(wp "$T/cp-spec-reads.json")
+r=$(cpo --spec-json "$SR"); cchk "reads and symbols" 3 "$r"
+cin "a read that moved" "[r1] a.txt:20-22  MOVED(+3)  -> a.txt:23-25"
+cin "a read on a deleted path is GONE" "[r2] c.txt:2-3  GONE (not named by the spec's deletes)"
+cin "a read absent at base is MISSING" "[r3] sub/a.txt:1-2  MISSING (read path absent at base)"
+cin "a present symbol adds no suffix" "[1] a.txt:20-22  MOVED(+3)  -> a.txt:23-25"
+cin "a missing symbol is named" "[2] b.txt:30-31  MOVED(-2) SYMBOL_MISSING b99"
+cin "an identifier matches whole words only" "MOVED(+3) SYMBOL_MISSING a2  -> a.txt:23-25"
+cin "a non-identifier symbol is a literal substring" "[4] sym.txt:9-9  SAME"
+cnot "the substring symbol is not missing" "SYMBOL_MISSING ::ba"
+cin "the read caption carries its why" "== READ r1: moved below the insertion  (a.txt:23-25  MOVED(+3))"
+cin "a GONE read prints its window at base" "== READ r2: deleted path  (c.txt:2-3 AT BASE"
+[ "$(grep -c '^\[' "$T/cp.out")" = 9 ] && echo "ok   context-pack the table lists edits and reads" || { echo "FAIL context-pack table rows with reads"; fail=1; }
+[ "$(grep -n '^== READ r1' "$T/cp.out" | cut -d: -f1)" -gt "$(grep -n '^== \[4\]' "$T/cp.out" | cut -d: -f1)" ] && echo "ok   context-pack read windows follow the edit windows" || { echo "FAIL context-pack read window order"; fail=1; }
+[ "$(grep -n '^CALLERS' "$T/cp.out" | head -1 | cut -d: -f1)" -gt "$(grep -n '^== READ r5' "$T/cp.out" | cut -d: -f1)" ] && echo "ok   context-pack caller lists follow the read windows" || { echo "FAIL context-pack caller list order"; fail=1; }
+cin "3 callers are all listed" "CALLERS needle_three: 3 hits in 1 files"
+cin "caller hit format" "zcallers.txt:2: needle_three call 2"
+cnot "the hit inside the symbol's own window is dropped" "sym.txt:5: def needle_three"
+cnot "a longer word is no caller" "needle_threefold"
+cin "60 hits print per-file counts" "CALLERS needle_many: 60 hits in 2 files"
+cin "per-file count line" "    30  many1.txt"
+cin "the narrowing command" "narrow: git grep -n -I -w -F -e needle_many -- <path>"
+cnot "60 hits print no hit lines" "many1.txt:1:"
+r=$(cpo --spec-json "$SR" --only r1); cchk "--only r1 keeps the exit of all anchors" 3 "$r"
+cin "--only r1 prints the read" "== READ r1: moved below the insertion"
+cnot "--only r1 prints no other read" "== READ r2"; cnot "--only r1 prints no edit window" "== [1]"
+r=$(cpo --spec-json "$SR" --only r9); cchk "--only past the reads" 2 "$r"; grep -qF "context-pack: --only: index outside reads" "$T/cp.err" && echo "ok   context-pack names the reads bound" || { echo "FAIL context-pack reads bound"; fail=1; }
+r=$(cpo --spec-json "$SR" --only 1,r4); cin "--only mixes edit and read labels" "CALLERS needle_many: 60 hits"; cnot "--only lists callers of the selected anchors only" "CALLERS b99"
+r=$(cpo --spec-json "$SR" --since "$(git -C "$R" rev-parse HEAD)"); cnot "--since HEAD prints no read window" "== READ"; cnot "--since HEAD prints no caller list" "CALLERS"
+r=$(cpo --spec-json "$SR" --max-lines 3); cchk "--max-lines below the table with reads" 3 "$r"
+[ "$(grep -c '^\[' "$T/cp.out")" = 9 ] && echo "ok   context-pack a small budget keeps every edit and read row" || { echo "FAIL context-pack small budget with reads"; fail=1; }
+cnot "a small budget prints no window" "== "; cnot "a small budget prints no caller list" "CALLERS"
+r=$(cpo --spec-json "$SR" --max-lines 60); cchk "caller lists cut by the budget" 3 "$r"
+[ "$(wc -l <"$T/cp.out" | tr -d ' ')" -le 60 ] && echo "ok   context-pack caller lists stay within --max-lines" || { echo "FAIL context-pack caller lists over budget"; fail=1; }
+cin "the cut caller lists are named" "callers not printed: "
+SUGG=$(grep -o '^callers not printed: .*--max-lines [0-9]*' "$T/cp.out" | grep -o '[0-9]*$')
+r=$(cpo --spec-json "$SR" --max-lines "$SUGG"); cnot "the suggested --max-lines prints every caller list" "callers not printed"
+[ "$(wc -l <"$T/cp.out" | tr -d ' ')" = "$SUGG" ] && echo "ok   context-pack suggested caller --max-lines is exact" || { echo "FAIL context-pack suggested caller max: $(wc -l <"$T/cp.out") vs $SUGG"; fail=1; }
+{ echo '{"base": "'$BASE'", "deletes": [], "file_changes": ['
+  for i in 1 2 3 4 5 6 7 8 9; do echo '{"change": "s'$i'", "location": {"path": "big.txt", "line": '$i', "end_line": '$i', "symbol": "g'$i'"}}'$([ $i -lt 9 ] && echo ,); done
+  echo ']}'; } >"$T/cp-spec9sym.json"
+r=$(cpo --spec-json "$(wp "$T/cp-spec9sym.json")" --max-lines 400); cchk "nine symbols" 0 "$r"
+[ "$(grep -c '^CALLERS' "$T/cp.out")" = 8 ] && echo "ok   context-pack at most 8 caller lists" || { echo "FAIL context-pack caller list count"; fail=1; }
+cin "the ninth symbol is named" "callers not listed: g9"
+echo '{"base": "'$BASE'", "deletes": [], "file_changes": [], "reads": [{"why": "w", "location": {"path": "a.txt", "line": 20, "end_line": 22, "symbol": "a21"}}]}' >"$T/cp-spec-r0.json"
+r=$(cpo --spec-json "$(wp "$T/cp-spec-r0.json")"); cchk "a spec of one read, symbol present" 0 "$r"
+cin "a read with a symbol present: no suffix" "[r1] a.txt:20-22  MOVED(+3)  -> a.txt:23-25  # w"
+# caller-list bounds: 50 hits list, 51 count; 20 files; a hit's text is cut at 160; CR and bad bytes
+{ echo '{"base": "'$BASE'", "deletes": [], "file_changes": ['
+  n=0; for sy in bound_fifty bound_fiftyone spread_sym long_symbol q.zq sym_bad twenty_sym; do n=$((n+1))
+    echo '{"change": "'$sy'", "location": {"path": "anchors.txt", "line": 1, "end_line": 1, "symbol": "'$sy'"}}'$([ $n -lt 7 ] && echo ,); done
+  echo ']}'; } >"$T/cp-specb.json"
+r=$(cpo --spec-json "$(wp "$T/cp-specb.json")" --max-lines 400); cchk "caller list bounds" 0 "$r"
+cin "exactly 50 hits are listed" "CALLERS bound_fifty: 50 hits in 1 files"
+[ "$(grep -c '^bound50.txt:' "$T/cp.out")" = 50 ] && echo "ok   context-pack 50 hits print as lines" || { echo "FAIL context-pack 50 hit lines"; fail=1; }
+cin "51 hits are counted" "CALLERS bound_fiftyone: 51 hits in 1 files"
+cin "51 hits: the per-file count" "    51  bound51.txt"
+cnot "51 hits print no hit lines" "bound51.txt:1:"
+grep -qx "(1 more files)" "$T/cp.out" && echo "ok   context-pack 21 files: the 21st is named" || { echo "FAIL context-pack 21st file line"; fail=1; }
+grep -qx "narrow: git grep -n -I -F -e q.zq -- <path>" "$T/cp.out" && echo "ok   context-pack the narrowing line is exact" || { echo "FAIL context-pack narrowing line"; fail=1; }
+cin "exactly 20 files name no more" "CALLERS twenty_sym: 60 hits in 20 files"
+[ "$(grep -c '(0 more files)' "$T/cp.out")" = 0 ] && echo "ok   context-pack 20 files print no more-files line" || { echo "FAIL context-pack 20 files"; fail=1; }
+[ "$(grep -c '^ *[34]  manyf/' "$T/cp.out")" = 20 ] && echo "ok   context-pack at most 20 files are counted" || { echo "FAIL context-pack file cap: $(grep -c '^ *[34]  manyf/' "$T/cp.out")"; fail=1; }
+cin "files are ranked by hits, largest first" "     4  manyf/f21.txt"
+[ "$(grep -n 'manyf/f21.txt' "$T/cp.out" | cut -d: -f1)" -lt "$(grep -n 'manyf/f01.txt' "$T/cp.out" | cut -d: -f1)" ] && echo "ok   context-pack the largest file prints first" || { echo "FAIL context-pack file order"; fail=1; }
+cin "a non-identifier narrowing command has no -w" "narrow: git grep -n -I -F -e q.zq -- <path>"
+LL=$(grep '^longline.txt:1: ' "$T/cp.out"); [ "${#LL}" = 176 ] && echo "ok   context-pack a hit's text is cut at 160 characters" || { echo "FAIL context-pack hit text length ${#LL}"; fail=1; }
+cnot "a CR in a hit is stripped" "$(printf '\r')"
+cin "a hit with invalid UTF-8 still prints" "bad.txt:1: sym_bad"
+cin "a hit keeps a trailing X and loses its CR" "endX"
+grep -qx "bad.txt:1: sym_bad .* endX" "$T/cp.out" && echo "ok   context-pack a hit ends at its last character" || { echo "FAIL context-pack hit end"; fail=1; }
+r=$(cpo --spec-json "$SR" --only 5); cchk "--only past the last edit anchor" 2 "$r"; grep -qxF "context-pack: --only: index outside file_changes" "$T/cp.err" && echo "ok   context-pack --only 5 is outside four anchors" || { echo "FAIL context-pack --only 5"; fail=1; }
+r=$(cpo --spec-json "$SR" --only 4); cchk "--only the last edit anchor" 3 "$r"; cin "--only 4 prints that window" "== [4] sym.txt:9-9"
+r=$(cpo --spec-json "$SR" --only r6); cchk "--only past the last read" 2 "$r"; grep -qxF "context-pack: --only: index outside reads" "$T/cp.err" && echo "ok   context-pack --only r6 is outside five reads" || { echo "FAIL context-pack --only r6"; fail=1; }
+r=$(cpo --spec-json "$SR" --only r5); cchk "--only the last read" 3 "$r"; cin "--only r5 prints that window" "== READ r5:"
+sed -n 3p "$T/cp.out" | grep -q '^\[r3\]' && echo "ok   context-pack a MISSING read sorts with the problem anchors" || { echo "FAIL context-pack MISSING read order"; fail=1; }
+cin "a GONE read checks its symbol at base" "GONE (not named by the spec's deletes) SYMBOL_MISSING c9"
+{ echo '{"base": "'$BASE'", "deletes": [], "file_changes": [{"location": {"path": "a.txt", "line": 1, "end_line": 2, "symbol": "zz9"}}],'
+  echo '"reads": [{"location": {"path": "a.txt", "line": 1, "end_line": 2}}, {"why": "'$(printf '%0250d' 0 | tr 0 w)'", "location": {"path": "a.txt", "line": 3, "end_line": 3}}]}'; } >"$T/cp-specw.json"
+r=$(cpo --spec-json "$(wp "$T/cp-specw.json")"); cchk "a missing symbol alone fails the run" 3 "$r"
+cin "a symbol absent from an unmoved window" "[1] a.txt:1-2  SAME SYMBOL_MISSING zz9"
+cnot "an anchor without a change or why gets no filler" "XXXX"
+W200=$(printf '%0200d' 0 | tr 0 w); cin "the read caption is cut at 200" "== READ r2: $W200  (a.txt:3-3"
+# the caller lists obey --max-lines at every budget, and the suggested value prints them all
+{ echo '{"base": "'$BASE'", "deletes": [], "file_changes": ['
+  for i in 1 2 3 4 5 6 7 8 9 10; do echo '{"change": "s'$i'", "location": {"path": "big.txt", "line": '$i', "end_line": '$i', "symbol": "g'$i'"}}'$([ $i -lt 10 ] && echo ,); done
+  echo ']}'; } >"$T/cp-spec10sym.json"; S10=$(wp "$T/cp-spec10sym.json")
+r=$(cpo --spec-json "$S10" --max-lines 400); cin "two symbols past the eighth are named together" "callers not listed: g9,g10"
+FULLN=$(wc -l <"$T/cp.out" | tr -d ' ')
+for b in $((FULLN-1)) $((FULLN-3)) $((FULLN-6)) $((FULLN-9)) $((FULLN-30)); do
+  r=$(cpo --spec-json "$S10" --max-lines "$b")
+  [ "$(wc -l <"$T/cp.out" | tr -d ' ')" -le "$b" ] && echo "ok   context-pack budget $b holds" || { echo "FAIL context-pack budget $b exceeded: $(wc -l <"$T/cp.out")"; fail=1; }
+  SG=$(grep -o '^callers not printed: .*--max-lines [0-9]*' "$T/cp.out" | grep -o '[0-9]*$')
+  if [ -n "$SG" ]; then r=$(cpo --spec-json "$S10" --max-lines "$SG"); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = "$FULLN" ] && ! grep -q 'callers not printed\|not expanded' "$T/cp.out" && echo "ok   context-pack budget $b: the suggestion prints everything" || { echo "FAIL context-pack budget $b: suggestion $SG gave $(wc -l <"$T/cp.out") of $FULLN"; fail=1; }; fi
+done
+r=$(cpo --spec-json "$S10" --max-lines $((FULLN-1))); [ "$(grep -c '^CALLERS' "$T/cp.out")" = 6 ] && echo "ok   context-pack one line short drops two lists for the note" || { echo "FAIL context-pack one line short: $(grep -c '^CALLERS' "$T/cp.out") lists"; fail=1; }
+cin "the dropped lists are named" "callers not printed: g7,g8: --max-lines $FULLN"
+# window budgets: the exact thresholds, and what the caller lists leave of them
+r=$(cpo --spec-json "$S1" --max-lines 104); cnot "104 lines expand no 100-line window" "== ["; cin "104 lines skip a 100-line window" "not expanded: --only 1"
+r=$(cpo --spec-json "$S1" --max-lines 105); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 105 ] && grep -qx "56 more lines: --only 1 --max-lines 160" "$T/cp.out" && echo "ok   context-pack 105 lines hold a capped window and its note" || { echo "FAIL context-pack 105-line budget"; fail=1; }
+S30=$(wp "$T/cp-spec30.json")
+r=$(cpo --spec-json "$S30" --max-lines 186); [ "$(grep -c '^== ' "$T/cp.out")" = 9 ] && [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 186 ] && echo "ok   context-pack 186 lines hold 9 windows and the note" || { echo "FAIL context-pack 186-line budget"; fail=1; }
+r=$(cpo --spec-json "$S30" --max-lines 185); [ "$(grep -c '^== ' "$T/cp.out")" = 8 ] && echo "ok   context-pack 185 lines hold 8 windows" || { echo "FAIL context-pack 185-line budget"; fail=1; }
+r=$(cpo --spec-json "$S30" --max-lines 542); [ "$(grep -c '^== ' "$T/cp.out")" = 30 ] && echo "ok   context-pack 542 lines hold all 30 windows" || { echo "FAIL context-pack 542-line budget"; fail=1; }; cnot "542 lines need no not-expanded note" "not expanded"
+for b in 530 531 532 533 534 535 536 537 538 539 540 541; do
+  r=$(cpo --spec-json "$S30" --max-lines $b); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" -le $b ] && grep -q '^not expanded: --only 30$' "$T/cp.out" && echo "ok   context-pack budget $b skips only the last window" || { echo "FAIL context-pack budget $b: $(wc -l <"$T/cp.out") lines"; fail=1; }
+done
+for b in 37 38 39 40 41 42 43 44 45 46 47; do
+  r=$(cpo --spec-json "$S30" --only 1,2 --max-lines $b); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = $b ] && [ "$(grep -c '^== ' "$T/cp.out")" = 1 ] && grep -q 'more lines: --only 1 ' "$T/cp.out" && echo "ok   context-pack --only 1,2 at $b lines truncates window 1 to fit" || { echo "FAIL context-pack --only 1,2 at $b: $(wc -l <"$T/cp.out") lines"; fail=1; }
+done
+r=$(cpo --spec-json "$S30" --only 1,2 --max-lines 36); cnot "--only 1,2 at 36 lines expands nothing" "== ["
+r=$(cpo --spec-json "$S10" --max-lines 94); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 94 ] && [ "$(grep -c '^== ' "$T/cp.out")" = 10 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 6 ] && echo "ok   context-pack one line short keeps every window and 6 lists" || { echo "FAIL context-pack 94-line S10"; fail=1; }
+r=$(cpo --spec-json "$S10" --max-lines 86); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 86 ] && [ "$(grep -c '^== ' "$T/cp.out")" = 9 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 5 ] && echo "ok   context-pack 86 lines: 9 windows, 5 lists, every note" || { echo "FAIL context-pack 86-line S10"; fail=1; }
+r=$(cpo --spec-json "$S10" --max-lines 65); [ "$(grep -c '^== ' "$T/cp.out")" = 7 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 0 ] && grep -q '^callers not printed: ' "$T/cp.out" && grep -q '^callers not listed: g9,g10' "$T/cp.out" && echo "ok   context-pack windows outrank caller lists" || { echo "FAIL context-pack 65-line S10"; fail=1; }
+r=$(cpo --spec-json "$SR" --max-lines 40); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 40 ] && [ "$(grep -c '^== ' "$T/cp.out")" = 3 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 2 ] && echo "ok   context-pack 40 lines: 3 windows, 2 lists, no line unused" || { echo "FAIL context-pack 40-line SR"; fail=1; }
+r=$(cpo --spec-json "$SR" --max-lines 44); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 44 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 3 ] && echo "ok   context-pack 44 lines: 3 lists" || { echo "FAIL context-pack 44-line SR"; fail=1; }
+r=$(cpo --spec-json "$SR" --max-lines 62); [ "$(wc -l <"$T/cp.out" | tr -d ' ')" = 61 ] && [ "$(grep -c '^CALLERS' "$T/cp.out")" = 4 ] && echo "ok   context-pack 62 lines: a list that needs 2 lines waits" || { echo "FAIL context-pack 62-line SR"; fail=1; }
 # usage and unreadable spec; no error echoes an input value
 r=$(cpo --spec-json "$SP" --max-lines CANARY-usage); cchk "bad --max-lines" 2 "$r"; cnot "usage error echoes no value" "CANARY-usage"
 r=$(cpo --spec-json "$T/CANARY-nofile.json"); cchk "unreadable --spec-json" 4 "$r"; grep -qF "context-pack: --spec-json: unreadable; --spec-json reads a saved view" "$T/cp.err" && echo "ok   context-pack names the unreadable --spec-json" || { echo "FAIL context-pack names the unreadable --spec-json"; fail=1; }; cnot "unreadable --spec-json echoes no path" "CANARY-nofile"
@@ -446,6 +780,14 @@ cases = {
  "deletes-str": (lambda v: v.update(deletes="CANARY-del"), "deletes"),
  "deletes-nopath": (lambda v: v.update(deletes=[{"note": "CANARY-note"}]), "deletes[1].path"),
  "deletes-entry-str": (lambda v: v.update(deletes=["CANARY-d"]), "deletes[1].path"),
+ "reads-str": (lambda v: v.update(reads="CANARY-reads"), "reads"),
+ "read-entry-str": (lambda v: v.update(reads=["CANARY-read"]), "reads[1]"),
+ "read-nolocation": (lambda v: v.update(reads=[{"why": "w"}]), "reads[1].location"),
+ "read-path": (lambda v: v.update(reads=[{"why": "w", "location": {"path": ["CANARY-p"], "line": 1}}]), "reads[1].location.path"),
+ "read-line": (lambda v: v.update(reads=[{"why": "w", "location": {"path": "a.txt", "line": "CANARY-l"}}]), "reads[1].location.line"),
+ "read-why": (lambda v: v.update(reads=[{"why": {"CANARY": 1}, "location": {"path": "a.txt", "line": 1}}]), "reads[1].why"),
+ "read-symbol": (lambda v: v.update(reads=[{"why": "w", "location": {"path": "a.txt", "line": 1, "symbol": 7}}]), "reads[1].location.symbol"),
+ "edit-symbol": (lambda v: v["file_changes"][0]["location"].update(symbol=["CANARY-s"]), "file_changes[1].location.symbol"),
 }
 names = []
 for name, (edit, field) in cases.items():