feat(orchestrator): board-roll.sh — auto-roll oldest LIVE-board entries to LEDGER under byte cap

Coordinator boards (MOS/MS-LEAD LIVE) enforce a <8KB discipline via a board-write
self-guard that ABORTs when over cap; coordinators then hand-trim + retry every
time (38 ABORT-OVER-CAP cycles observed in one 24h window). board-roll.sh
automates that trim mechanically and reversibly: oldest archival ticks move to the
append-only LEDGER instead of being hand-deleted.

Conservative by design — only content inside explicit
<!-- BOARD-ROLL:START -->/<!-- BOARD-ROLL:END --> markers is eligible; pinned
title/blockquote/curated ## sections are never touched. Rolls whole oldest
(bottom-most) ### entry blocks until LIVE is under cap or the zone is empty.
No markers -> exit 3, no change (never guesses). Byte-accurate cap (UTF-8 safe),
atomic writes (temp+mv, LEDGER first), --dry-run, --help exits 0 (#701 discipline).

- board-roll.sh: the tool (self-documented header + usage)
- test-board-roll.sh: 7-group regression harness (under-cap no-op, no-markers
  exit 3, roll-oldest-until-under-cap, LEDGER fidelity, dry-run inertness,
  unsatisfiable-cap exit 3, help/bad-flag exit codes)
- README.md: orchestrator/ tool index + board-roll contract & usage

Shared-runtime helper: authored by enhance lane, STOP at PR-open; merge authority
is the coordinator's after the review gate (AGENTS.md rule 38). Deploy-gap caveat
per #701/#702: SSOT fix lands on web1 only on framework redeploy.

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

packages/mosaic/framework/tools/orchestrator/README.md

@@ -0,0 +1,80 @@
+# orchestrator/ tools
+
+Helper scripts for r0 coordinator / orchestrator sessions — mission lifecycle,
+session health, continuation, and board maintenance. See
+`framework/guides/ORCHESTRATOR-PROTOCOL.md` for the surrounding process.
+
+| Script | Purpose |
+|--------|---------|
+| `mission-init.sh` | Initialize a new orchestration mission (manifest, scratchpad, TASKS.md). |
+| `mission-status.sh` | Show the mission progress dashboard. |
+| `session-run.sh` | Generate continuation context and launch the target runtime. |
+| `session-resume.sh` | Crash recovery for dead orchestrator sessions. |
+| `session-status.sh` | Check agent session health. |
+| `continue-prompt.sh` | Generate the continuation prompt for the next session. |
+| `board-roll.sh` | Keep a LIVE orchestration board under its byte cap by rolling the oldest entries to its LEDGER. |
+| `smoke-test.sh` | Behavior smoke checks for the coord continue/run workflows. |
+| `test-board-roll.sh` | Regression harness for `board-roll.sh`. |
+| `_lib.sh` | Shared functions sourced by the above (state files, TASKS.md parsing, locks). |
+
+## board-roll.sh
+
+Coordinator boards (`MOS-ORCHESTRATION-BOARD-LIVE.md`, `MS-LEAD-BOARD-LIVE.md`)
+follow a **"< 8 KB LIVE"** discipline: the LIVE board is the only file loaded on
+resume, so it must stay small, and history lives in an append-only LEDGER. When a
+board write would push LIVE over its cap, coordinators otherwise hand-trim and
+retry every time — an observed 38 ABORT-OVER-CAP cycles in one 24 h window.
+`board-roll.sh` automates that trim mechanically and reversibly: the audit trail
+is moved to the LEDGER instead of being hand-deleted.
+
+### Contract (conservative — it never guesses what is safe to move)
+
+The LIVE board opts in by wrapping its aging archival ticks in an explicit roll
+zone. Everything **outside** the markers (title, protocol blockquote, curated
+always-current `##` sections) is pinned and never touched:
+
+```markdown
+# MOS ORCHESTRATION BOARD — LIVE state
+> protocol blockquote … (pinned)
+
+## 🟦 Curated always-current section (pinned)
+…
+
+<!-- BOARD-ROLL:START -->
+### 2026-07-22 (mid²²) — newest tick, stays longest
+…
+### 2026-07-20 (dawn) — oldest tick, rolled first
+…
+<!-- BOARD-ROLL:END -->
+```
+
+Inside the zone, entries are delimited by a heading marker (default `### `) and
+are assumed **newest-first (top) → oldest-last (bottom)**. `board-roll.sh` moves
+whole oldest (bottom-most) entry blocks out of the zone and appends them verbatim
+to the LEDGER, one at a time, until LIVE is back under the cap or the zone is
+empty. If the board has no markers, it exits `3` and changes nothing — adding the
+markers is a deliberate opt-in by the board owner.
+
+### Usage
+
+```bash
+board-roll.sh --live <LIVE.md> --ledger <LEDGER.md> [options]
+
+  --live   <path>    LIVE board file (required)
+  --ledger <path>    append-only LEDGER file (required; created if absent)
+  --cap    <bytes>   size ceiling for LIVE (default 8192)
+  --marker <prefix>  entry-heading prefix inside the roll zone (default "### ")
+  --dry-run          report what would move; change nothing
+  -h, --help         show help and exit 0
+```
+
+Exit codes: `0` LIVE under cap (already, or after rolling) — on `--dry-run`, a
+plan exists or nothing to do · `2` usage / argument / IO error · `3` cannot meet
+the cap (no markers, or the pinned sections alone exceed the cap and need a manual
+trim).
+
+Writes are atomic (temp file + `mv`, LEDGER first) so a failure never leaves a
+board half-written; line endings are normalized to LF on rewrite. `--dry-run`
+first is recommended when wiring it into a board update protocol.
+
+Run the regression suite with `bash test-board-roll.sh`.