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

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

Only one roll zone is supported. If a board carries more than one BOARD-ROLL:START/END pair, board-roll.sh refuses (exit 3, zero changes) rather than span first-START..last-END and relocate the curated content between the zones — consolidate the ticks into a single zone instead.

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, more than one marker pair, 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.