┌────────────┐
    │  WRITTEN   │  Leaf writes bookbag with empty verdicts
    └─────┬──────┘
          │
    ┌─────▼──────┐      ◄── Phase 1 shortcut: WRITTEN → REVIEWED
    │  CTO_REV'D │  Teacher CTO fills cto_verdict (PASS|FAIL)        ──── Phase 2 only
    └─────┬──────┘
          │
    ┌─────▼──────┐
    │  COO_REV'D │  Teacher COO fills coo_verdict (PASS|FAIL)        ──── Phase 2 only
    └─────┬──────┘
          │
     ┌────▼────┐
     │ REVIEWED│  Both verdicts present and accepted is computed
     └────┬────┘
          │
     ┌────▼──────┐
     │ SCORED    │  Principal calls evaluate_and_update() — in Phase 1 this
     └────┬──────┘  is done inside run_task() before signal_ready()
          │
     ┌────▼──────┐
     │ DISPOSED  │  Leaf worktree removed; bookbag archived
     └───────────┘

{
    "bead": str,           # unique task ID, e.g. "coder-python-coding-a1b2c3d4"
    "task": str | None,    # task description
    "student": str,        # role that handled it (coder, searcher, etc.)
    "domain": str,         # task domain
    "difficulty": str,     # easy / medium / hard / blocker
    "output": str,         # student's raw LLM response
    "lens": str,           # review lens applied ("cto" / "coo")
    "cto_verdict": str,    # PASS or FAIL (technical correctness)
    "coo_verdict": str,    # PASS or FAIL (completeness / acceptance criteria)
    "findings": [          # combined review findings
        {"section": str, "severity": str, "description": str, ...}
    ],
    "ac_met": [str],       # acceptance criteria satisfied
    "files_changed": [str],
    "verification": str,   # build/test output
    "summary": str,        # human-readable summary
    "blockers": [str],     # anything blocking completion
    "accepted": bool,      # true if both CTO and COO passed
    "timestamp": str       # ISO-8601 UTC
}

Leaf                                           Teacher
 │                                               │
 ├── write_bookbag(bead, ...)                    │
 │     → ~/.hermes/bookbag/<bead>.json           │
 │                                               │
 ├── BookbagSignal(bead).ready()                 │
 │     → ~/.hermes/signals/<bead>.ready  ────────┤
 │                                               ├── poll: signal.check()?
 │                                               │     → reads .ready file
 │                                               │
 │                                               ├── if ready:
 │                                               │     read_bookbag(bead)
 │                                               │     → ~/.hermes/bookbag/<bead>.json
 │                                               │
 │                                               ├── locked_update_bookbag(...)
 │                                               │
 │                                               └── BookbagSignal(bead).clear()
 │                                                     → removes .ready file

class BookbagSignal:
    """Fast flag-file signaling for bookbag handoff.

    Instead of polling the bookbag JSON file (which requires parsing JSON
    on every poll), use a lightweight `.ready` flag file.
    """

    def ready(self) -> None:
        """Signal that this bead's bookbag is ready for review.
        Writes ~/.hermes/signals/<bead>.ready
        """
        ...

    def check(self) -> bool:
        """Check if the ready signal exists."""
        return self._ready_path.exists()

    def clear(self) -> None:
        """Clear the ready signal after handoff is complete.
        Removes ~/.hermes/signals/<bead>.ready
        """
        ...

def acquire_lock(bead: str, timeout: float = 10.0) -> bool:
    """Acquire a file lock for a bead.

    Uses filesystem atomicity: O_EXCL on open() fails if the lock file
    already exists. Polls every 0.5s until acquired or timeout.

    Writes PID to the lock file for stale-lock detection.
    """

def release_lock(bead: str) -> None:
    """Release a file lock for a bead. Best-effort."""
    lock_path = LOCK_DIR / f"{bead}.lock"
    try:
        lock_path.unlink(missing_ok=True)
    except OSError:
        pass

def locked_update_bookbag(bead: str, lock_timeout: float = 10.0, **kwargs) -> dict | None:
    """Update a bookbag with lock protection.

    1. acquire_lock(bead, lock_timeout)  — blocks until lock or timeout
    2. read_bookbag(bead)                — read current state
    3. bag.update(kwargs)                — apply changes in memory
    4. write_bookbag(bead, **bag)        — write back
    5. release_lock(bead)                — always in finally block

    Returns updated dict, or None if lock could not be acquired
    or bookbag doesn't exist.
    """

                 ┌─────────┐
                 │  BOOT   │  Create or rediscover worktree
                 └────┬────┘
                      │
                 ┌────▼────┐
          ┌──────┤  SLEEP  │  Persist state, consolidate, log
          │      └────┬────┘
          │           │
          │      ┌────▼────┐
          │      │  WAKE   │  Restore state from last sleep
          │      └────┬────┘
          │           │
          │      ┌────▼────────┐
          │      │  REVIEW     │  Poll for un-reviewed bookbags
          │      │              │  that match this teacher's lens
          │      └────┬────────┘
          │           │
          └───────────┘

class TeacherWorktree:
    def boot(self) -> str:
        """Create or rediscover persistent teacher worktree.

        Tries Orca worktree creation first. If the worktree already
        exists (restart scenario), scans Orca's worktree list for a
        matching name and redisovers it.

        Returns: Absolute path to the teacher's worktree.
        """

    def sleep(self, duration_minutes: float = 0.0) -> dict:
        """Execute sleep sequence:
        1. Freeze: stop accepting new review tasks
        2. Consolidate: compress episodic history → YAML summary
        3. Persist: save SleepState to data/sessions/<session_id>.json
        4. Log: record sleep event to Library Log
        """

    def wake(self) -> dict:
        """Execute wake sequence:
        1. Load: read persisted SleepState from disk
        2. Hydrate: load ConsolidationArtifact for context
        3. Resume: log wake event to Library Log

        Graceful on first boot: if no session exists, returns empty
        state instead of crashing.
        """

    def review_cycle(self) -> int:
        """Poll for un-reviewed bookbags and review one if found.

        1. list_bookbags() — all beads on disk
        2. For each bead: read bookbag, check if this teacher's
           verdict field is empty
        3. If found: build task dict, run AdversarialReviewer
        4. locked_update_bookbag(bead, cto_verdict/cod_verdict=...)
        5. Record in episodic history

        Returns: 1 if reviewed, 0 if none found.
        """

    def run_loop(self) -> None:
        """Infinite sleep/wake/review cycle.

        Designed to run inside the teacher's worktree terminal:
            python -c "from teacher import TeacherWorktree; 
                        TeacherWorktree('cto').run_loop()"

        Every 10 cycles, prunes old session data.
        """

    def prune_sessions(self, max_cycles: int = 10) -> int:
        """Remove old session files beyond retention limit.

        Keeps only the most recent `max_cycles` session JSON and
        consolidation YAML files. Prevents unbounded data growth.
        """

    ┌──────────┐
    │  BOOT    │  Create Orca child worktree
    └────┬─────┘
         │
    ┌────▼──────┐
    │  BRIEF    │  Write StudentBrief to .hermes/briefs/<bead>.json
    └────┬──────┘
         │
    ┌────▼────────┐
    │  RUN_TASK   │  Execute director.run_task() (LLM + bookbag + review)
    └────┬────────┘
         │
    ┌────▼────────┐
    │  OUTPUT     │  Write audit trail to .hermes/outputs/<bead>.json
    └────┬────────┘
         │
    ┌────▼────────┐
    │  SIGNAL     │  Write .hermes/signals/<bead>.ready flag
    └────┬────────┘
         │
    ┌────▼────────────┐
    │  WAIT_HANDOFF * │  Phase 2 only: poll for teacher verdicts
    └────┬────────────┘
         │
    ┌────▼─────────┐
    │  DISPOSE     │  Remove Orca worktree, idempotent
    └──────────────┘

class StudentLeaf:
    def boot(self) -> str:
        """Create the disposable student worktree.

        Creates a proper Orca child worktree named `study-{role}-{rand8}`.
        Wraps OrcaUnavailableError in LeafError.
        """

    def write_brief(self, task_prompt: str) -> Path:
        """Write a StudentBrief to .hermes/briefs/<bead>.json.

        The brief is the task contract: bead, role, domain, task, difficulty.
        """

    def run_task(self, task_prompt: str) -> dict:
        """Execute the task via director.run_task().

        Phase 1: synchronous — LLM call + bookbag write + CTO/COO review
        all happen in the principal process. The result dict contains
        response, review, scores.

        Phase 2: async — only the LLM call. Bookbag written with empty
        verdicts. Teachers fill verdicts asynchronously.
        """

    def write_output(self, data: dict) -> Path:
        """Write audit trail to .hermes/outputs/<bead>.json.

        Full record: response, review, findings, scores, all structured.
        """

    def signal_ready(self) -> None:
        """Signal teachers bookbag is ready.

        Creates BookbagSignal(bead).ready() — writes
        ~/.hermes/signals/<bead>.ready flag file.
        """

    def wait_for_handoff(self, timeout: float | None = None) -> tuple[str, str]:
        """Wait for CTO and COO verdicts.

        Delegates to wait_for_verdicts(). In Phase 1 this is a no-op
        (verdicts already filled). In Phase 2 this polls until both
        verdicts appear.

        Returns: (cto_verdict, coo_verdict)
        """

    def dispose(self) -> None:
        """Remove the worktree. Idempotent.

        Calls close_worktree() on OrcaExecutionManager, clears all
        references. Safe to call multiple times.
        """

study-coder-a1b2c3d4/
  └── .hermes/
      ├── briefs/
      │   └── coder-python-coding-a1b2c3d4.json   # StudentBrief
      └── outputs/
          └── coder-python-coding-a1b2c3d4.json    # Audit trail

~/.hermes/
  ├── bookbag/
  │   └── coder-python-coding-a1b2c3d4.json        # Ground-truth bookbag
  ├── signals/
  │   └── coder-python-coding-a1b2c3d4.ready       # Ready flag
  └── locks/
      └── coder-python-coding-a1b2c3d4.lock         # Write lock

def run_leaf(task_prompt, role, domain, difficulty, store) -> dict:
    leaf = StudentLeaf(role, domain, difficulty, store)
    try:
        leaf.boot()
        leaf.write_brief(task_prompt)
        result = leaf.run_task(task_prompt)
        if result.get("status") == "success":
            leaf.write_output(output_data)
            leaf.signal_ready()
            # Phase 2: cto, coo = leaf.wait_for_handoff()
        return result
    finally:
        leaf.dispose()  # always runs

# Quick handoff (fast LLMs):
HANDOFF_TIMEOUT=60 HANDOFF_POLL_INTERVAL=2 python conductor.py --loop --rounds 10

# Slow handoff (complex reviews, slow models):
HANDOFF_TIMEOUT=300 HANDOFF_POLL_INTERVAL=10 python conductor.py --loop --rounds 5

# Teacher with custom poll rate:
python teacher.py --role cto --poll-interval 2.0

# Cross-project: set in .env or shell profile:
export HANDOFF_TIMEOUT=120
export HANDOFF_POLL_INTERVAL=5

Principal                          Leaf                    Teacher CTO          Teacher COO
─────────                          ────                    ───────────          ───────────
                                                                                      
  │                                │                       │                    │     
  ├── create worktree (teacher-cto)──┐                    │                    │     
  │                                │                       │                    │     
  ├── create worktree (teacher-coo)─────────────────────────┼────────────────────┤     
  │                                │                       │                    │     
  ├── start teacher loop (cto) ──────────────────────────────►  run_loop()      │     
  │                                │                       │  sleep()           │     
  ├── start teacher loop (coo) ────────────────────────────────┼────────────────►     
  │                                │                       │                    │  sleep()
  │                                │                       │                    │     
  ├── run_leaf(task) ──────────────► boot()                │                    │     
  │                                ├── write_brief()       │                    │     
  │                                ├── run_task()          │                    │     
  │                                │   ├── LLM call        │                    │     
  │                                │   ├── write_bookbag   │                    │     
  │                                │   ├── CTO review      ► wake() + review()  │     
  │                                │   ├── COO review      ─────────────────────► wake() + review()
  │                                │   └── score           │                    │     
  │◄───────────────────────────────┤   return result       │                    │     
  │  evaluate_and_update(result)   │                       │                    │     
  │                                ├── write_output()      │                    │     
  │                                ├── signal_ready()      │                    │     
  │                                ├── dispose()           │                    │     
  │                                │                       │                    │     
  │◄── result with scores ─────────┤                       │                    │