# 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
```

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`.