406a8464f9
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>
3.6 KiB
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:
# 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
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.