syncmill 0.2.0__py3-none-any.whl

syncmill/board.py

@@ -0,0 +1,2060 @@
+"""Persistent agent work-board (Phase 1) — the data foundation.
+
+syncmill today is a single-run, stateless orchestrator: a ``Task`` is one
+ephemeral prompt, gone after the run. The board adds durable, *structured* records
+of a multi-agent team's work — the goal, who owns which piece, what's blocked and
+why, what's done **and verified**, whether work is being duplicated, and where a
+human must step in. For an orchestration harness this is the infrastructure that
+makes collaboration *measurable*.
+
+**Why SQLite, not memtomem.** memtomem stores markdown+embedding *knowledge*
+chunks — no structured status/dependency fields, no state machine, no atomic
+compare-and-swap. The board needs exactly those, so it gets its own SQLite store
+at ``~/.syncmill/board.db`` (a flat module, gateway/monitor/session precedent —
+don't pre-abstract into a subpackage). *State lives only on the board; knowledge
+lives only in memtomem's ``shared``; the two cross-link by id* (the Supervisor
+writes one sanitized ``board-result:{item_id}`` summary to ``shared`` after a run).
+
+**Load-bearing, built LAZILY.** The board is the source of work and the system of
+record, so — unlike memory/breaker, which degrade silently — a corrupt/unusable
+board RAISES :class:`BoardError` rather than running untracked work or re-running
+``done`` items. It is disabled by default (:func:`build_board` → ``None``) and the
+Supervisor builds it lazily (NOT in ``__init__``), so an enabled-but-corrupt board
+can never break a plain ``syncmill run`` that never touches it.
+
+**Agents stay pure.** Orchestrated agents NEVER touch the board. The Supervisor
+mediates: it renders an item into the prompt (:func:`render_item_prompt`) and
+parses an OPTIONAL ``syncmill-board`` fenced block back out of the agent's output
+(:func:`parse_board_update` — its own parser, strict, degrade-to-``{}``, never
+raises, in the spirit of ``DecomposeStrategy._parse_subtasks``).
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import math
+import os
+import sqlite3
+import time
+import uuid
+from collections.abc import Iterable
+from dataclasses import asdict, dataclass, field
+from enum import StrEnum
+from pathlib import Path
+from typing import Callable
+
+from syncmill.artifacts import printable_name as _p
+from syncmill.platform_support import require_supported_platform
+from syncmill.config import BoardConfig
+from syncmill.models import TaskResult, TaskStatus
+from syncmill.review_candidates import ReviewItemSpec
+
+logger = logging.getLogger(__name__)
+_SQLITE_SIDECARS = ("-wal", "-shm", "-journal")
+
+
+def _prepare_private_board(path: Path) -> None:
+    """Create/tighten POSIX board storage without a process-global umask.
+
+    The `os.name` gate below is what keeps the Unix-only `os.fchmod` here safe —
+    unlike the `getattr` guards elsewhere, this whole hardening block is a POSIX
+    permission-model decision, so the platform check has to happen anyway and a
+    second per-call guard under it would be unreachable. An `OSError` from the
+    tightening is deliberately not swallowed: it becomes a `BoardError`.
+    """
+    parent_missing = not path.parent.exists()
+    path.parent.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if os.name != "posix":
+        return
+    if parent_missing:
+        os.chmod(path.parent, 0o700)
+    fd = os.open(path, os.O_CREAT | os.O_RDWR, 0o600)
+    try:
+        os.fchmod(fd, 0o600)
+    finally:
+        os.close(fd)
+    _tighten_board_files(path)
+
+
+def _tighten_board_files(path: Path) -> None:
+    if os.name != "posix":
+        return
+    os.chmod(path, 0o600)
+    for suffix in _SQLITE_SIDECARS:
+        try:
+            os.chmod(Path(f"{path}{suffix}"), 0o600)
+        except FileNotFoundError:
+            pass
+
+
+#: Columns added to an existing table after its CREATE shipped. `CREATE TABLE IF
+#: NOT EXISTS` is a no-op on a board that already exists, so every column added
+#: later needs an explicit ALTER — keep new nullable columns here, in order.
+_ADDED_COLUMNS: tuple[tuple[str, str, str], ...] = (
+    ("board_run_namespaces", "reclaimed_at", "REAL"),
+    # Purge-failure backoff (P0-6): a namespace whose purge keeps raising (a
+    # symlinked source, an unmounted index root, a legacy shared day file) must
+    # not stay the OLDEST collectible row forever — retried first every sweep,
+    # it consumes the whole GC budget and starves every healthy namespace
+    # behind it while the store grows monotonically.
+    ("board_run_namespaces", "failed_attempts", "INTEGER"),
+    ("board_run_namespaces", "next_attempt_at", "REAL"),
+)
+
+
+def _add_missing_columns(conn: sqlite3.Connection) -> None:
+    for table, column, decl in _ADDED_COLUMNS:
+        existing = {
+            row["name"] for row in conn.execute(f"PRAGMA table_info({table})")
+        }
+        if column in existing:
+            continue
+        try:
+            conn.execute(f"ALTER TABLE {table} ADD COLUMN {column} {decl}")
+        except sqlite3.OperationalError as exc:
+            # The check and the ALTER are two statements, so two processes
+            # opening an old board at once both see the column missing and both
+            # try to add it. The loser's failure means the column now EXISTS,
+            # which is all this function was asked to guarantee — anything else
+            # is a real error and still raises.
+            if "duplicate column" not in str(exc).lower():
+                raise
+
+
+class BoardError(RuntimeError):
+    """A board operation failed in a way that must NOT be silently degraded.
+
+    The board is the source of work and the system of record, so — unlike memory
+    or the circuit breaker, which are advisory — a board failure (corrupt db, a
+    rejected ``done`` transition, an unknown state) surfaces. The CLI converts it
+    to a clean ``click.ClickException`` (the ``session.SessionLaunchError``
+    "no fallback — it IS the feature" contract)."""
+
+
+# ── State machine + value types ──────────────────────────────────────────────
+
+
+class WorkState(StrEnum):
+    """The work-item lifecycle: ``planned → running → (blocked | review) → done``.
+
+    ``review`` vs ``done`` is the load-bearing distinction: ``review`` means the
+    agent finished but the work is **not yet verified**; ``done`` means
+    **done AND verified** — a transition to ``done`` requires structured passing
+    :class:`Evidence` (or a human sign-off), enforced in :meth:`Board.transition`.
+    """
+
+    PLANNED = "planned"
+    RUNNING = "running"
+    BLOCKED = "blocked"
+    REVIEW = "review"
+    DONE = "done"
+
+
+#: Terminal-ish states an item rests in once it leaves ``running``. Used to clear
+#: the lease (a claim is consumed the moment the item stops running).
+_STATES = frozenset(s.value for s in WorkState)
+
+
+@dataclass
+class Evidence:
+    """One structured proof that an item's work was verified — the thing the
+    ``done`` gate counts. ``kind`` is ``"gate"`` (a passing ``GateReport`` maps to
+    one), ``"test"``, ``"manual"`` (a human-attached ref), ``"human"`` (a
+    sign-off), or ``"tracegraph"`` (non-passing failure evidence imported for
+    review). ``passed`` is the verdict; ``ref`` names the evidence (a gate summary,
+    a CI url, …); ``by`` is who/what produced it; ``at`` is wall-clock."""
+
+    kind: str
+    ref: str
+    passed: bool
+    at: float
+    by: str = ""
+
+
+@dataclass
+class WorkItem:
+    """One tracked unit of team work. Lives here (not ``models.py``) because — like
+    ``breaker._AgentState`` — it never flows through a strategy; only the board and
+    the Supervisor's ``run_item`` touch it.
+
+    ``owner_agent`` is RECORD-ONLY in v1 (stamped from ``result.agent_id`` after a
+    run), not an assignment constraint — so ``board add`` has no ``--owner``.
+    """
+
+    id: str
+    goal: str
+    task: str
+    state: WorkState = WorkState.PLANNED
+    owner_agent: str | None = None
+    inputs: list[str] = field(default_factory=list)
+    outputs: list[str] = field(default_factory=list)
+    evidence: list[Evidence] = field(default_factory=list)
+    handoff: str = ""
+    human_required: bool = False
+    blocked_reason: str = ""
+    depends_on: list[str] = field(default_factory=list)
+    lease_run_id: str | None = None
+    claimed_at: float | None = None
+    created_at: float = 0.0
+    updated_at: float = 0.0
+
+
+@dataclass
+class Decision:
+    """A team decision that must NOT be re-litigated (Phase 2).
+
+    Decisions are orthogonal to work items: they carry no state machine, no lease —
+    they are durable, deterministically-injected context. ``scope`` is ``""`` for a
+    GLOBAL decision (applies to every item) or a goal string for a goal-scoped one;
+    :func:`render_item_prompt` injects the active (non-superseded) decisions that
+    apply to an item's goal IN FULL, never via top-k recall. A decision is retired by
+    being ``superseded`` (a new decision replaces it), not deleted — the record is
+    append-only so the history of what was decided, and when, survives."""
+
+    id: str
+    text: str
+    scope: str = ""
+    created_at: float = 0.0
+    superseded_by: str | None = None
+    superseded_at: float | None = None
+
+
+@dataclass
+class BoardStats:
+    """A snapshot of team-health signals (Phase 2) — see :meth:`Board.stats`. The
+    list-valued fields carry the offending item ids (so a caller can drill in), and
+    the renderer reports their counts; ``stall_seconds`` echoes the aging window the
+    snapshot used so the report is self-describing."""
+
+    total: int
+    by_state: dict[str, int]
+    false_done: list[str]
+    redispatched: list[str]
+    reclaimed_stale: int
+    blocked_aged: list[str]
+    human_required_aged: list[str]
+    dropped_handoffs: list[str]
+    stall_seconds: int
+
+
+@dataclass(frozen=True)
+class ReviewImportResult:
+    """Outcome of one atomic Tracegraph review-candidate import."""
+
+    imported: int
+    skipped: int
+    item_ids: tuple[str, ...]
+    #: Of the skipped items, how many were requested under a DIFFERENT goal
+    #: than the one they already carry. Goal is assigned only on first import
+    #: (by design, test-locked) — this count lets the CLI say so instead of a
+    #: bare "skipped N existing" that reads as if the new goal took effect.
+    goal_kept: int = 0
+
+
+# ── SQLite schema ────────────────────────────────────────────────────────────
+
+_SCHEMA = """
+CREATE TABLE IF NOT EXISTS work_items (
+    id            TEXT PRIMARY KEY,
+    goal          TEXT NOT NULL DEFAULT '',
+    task          TEXT NOT NULL,
+    state         TEXT NOT NULL DEFAULT 'planned'
+                  CHECK (state IN ('planned','running','blocked','review','done')),
+    owner_agent   TEXT,
+    inputs        TEXT NOT NULL DEFAULT '[]',
+    outputs       TEXT NOT NULL DEFAULT '[]',
+    evidence      TEXT NOT NULL DEFAULT '[]',
+    handoff       TEXT NOT NULL DEFAULT '',
+    human_required INTEGER NOT NULL DEFAULT 0,
+    blocked_reason TEXT NOT NULL DEFAULT '',
+    depends_on    TEXT NOT NULL DEFAULT '[]',
+    lease_run_id  TEXT,
+    claimed_at    REAL,
+    created_at    REAL NOT NULL,
+    updated_at    REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_work_items_state ON work_items(state);
+CREATE INDEX IF NOT EXISTS idx_work_items_goal  ON work_items(goal);
+CREATE INDEX IF NOT EXISTS idx_work_items_owner ON work_items(owner_agent);
+CREATE INDEX IF NOT EXISTS idx_work_items_lease ON work_items(lease_run_id);
+-- list_recent walks this index backwards and stops at its LIMIT (#167);
+-- without it a newest-first read is a full scan plus a temp B-tree sort.
+CREATE INDEX IF NOT EXISTS idx_work_items_created ON work_items(created_at);
+
+CREATE TABLE IF NOT EXISTS transitions (
+    id         INTEGER PRIMARY KEY AUTOINCREMENT,
+    item_id    TEXT NOT NULL,
+    from_state TEXT,
+    to_state   TEXT NOT NULL,
+    actor      TEXT NOT NULL DEFAULT '',
+    note       TEXT NOT NULL DEFAULT '',
+    at         REAL NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_transitions_item ON transitions(item_id);
+-- stats() runs on every TUI poll tick (2s) over the append-only, never-pruned
+-- transitions table; without these its two audit queries are full-table scans
+-- that grow with total board history.
+CREATE INDEX IF NOT EXISTS idx_transitions_redispatch
+    ON transitions(from_state, to_state, item_id);
+CREATE INDEX IF NOT EXISTS idx_transitions_reclaim
+    ON transitions(to_state, note);
+
+CREATE TABLE IF NOT EXISTS decisions (
+    id            TEXT PRIMARY KEY,
+    text          TEXT NOT NULL,
+    scope         TEXT NOT NULL DEFAULT '',
+    created_at    REAL NOT NULL,
+    superseded_by TEXT,
+    superseded_at REAL
+);
+CREATE INDEX IF NOT EXISTS idx_decisions_scope  ON decisions(scope);
+CREATE INDEX IF NOT EXISTS idx_decisions_active ON decisions(superseded_by);
+
+-- reclaimed_at records when stale recovery took this run's lease. A reclaim
+-- means "presumed dead", not "known dead", so the scratch namespace gets a grace
+-- period before collection (see collectible_board_run_ids). Keep comments OUT of
+-- the CREATE body: sqlite stores the statement text verbatim and re-parses it on
+-- ALTER TABLE ... DROP COLUMN, where an inline comment truncates the input.
+CREATE TABLE IF NOT EXISTS board_run_namespaces (
+    run_id       TEXT PRIMARY KEY CHECK (run_id <> ''),
+    item_id      TEXT NOT NULL,
+    claimed_at   REAL NOT NULL,
+    purged_at    REAL,
+    reclaimed_at REAL
+);
+CREATE INDEX IF NOT EXISTS idx_board_run_namespaces_purged
+    ON board_run_namespaces(purged_at, claimed_at);
+
+-- Aggregate-then-trim rollups for `board compact` (#118): the transitions
+-- audit is append-only, so trimming old rows must first fold what stats()
+-- derives from them — per-item claim counts (redispatched) and the global
+-- stale-reclaim count — into these tables, which stats() reads additively.
+CREATE TABLE IF NOT EXISTS transition_rollups (
+    item_id     TEXT PRIMARY KEY,
+    claim_count INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS transition_counters (
+    name  TEXT PRIMARY KEY,
+    value INTEGER NOT NULL DEFAULT 0
+);
+
+"""
+
+# ── scratch-ledger backfills ────────────────────────────────────────────────
+#
+# Past WAL/schema initialization these are the only conditional data writes in the
+# open path (a DELETE-mode db still writes converting to WAL, and a pre-`reclaimed_at`
+# db writes once through `_add_missing_columns` — both one-time migrations). They are
+# deliberately NOT part of `_SCHEMA`: an INSERT takes the write lock at statement start whether
+# or not its SELECT matches a row, so running them unconditionally made EVERY open
+# a writer. That includes the per-run lease heartbeat's own connection, which then
+# waits out `busy_timeout` behind a concurrent `BEGIN IMMEDIATE` and can raise —
+# killing the heartbeat and letting the lease expire under a live run, whose item
+# is then reclaimed and dispatched a second time. Each backfill is now preceded by
+# a cheap read that decides whether the write is needed at all, so a steady-state
+# open is read-only.
+
+#: Every historical board claim recorded run_id as the transition actor. Only scan
+#: that history when the ledger is empty; retained purged rows make later opens skip it.
+#: The emptiness test is kept INSIDE the statement as well as in the read guard: the
+#: guard makes the steady-state open read-only, but only the in-statement `NOT EXISTS`
+#: is atomic — between a bare guard read and the INSERT another process can commit a
+#: claim, and this migration would then resurrect historical rows beside it (which the
+#: scratch GC later treats as collectible).
+_BACKFILL_LEDGER_FROM_AUDIT = """
+INSERT OR IGNORE INTO board_run_namespaces (run_id, item_id, claimed_at, purged_at)
+SELECT actor, MIN(item_id), MIN(at), NULL
+FROM transitions
+WHERE from_state='planned' AND to_state='running'
+  AND note='claimed' AND actor <> ''
+  AND NOT EXISTS (SELECT 1 FROM board_run_namespaces)
+GROUP BY actor
+"""
+
+#: Defensive legacy/corruption backfill for a live lease whose audit row is absent.
+_BACKFILL_LEDGER_FROM_LEASES = """
+INSERT OR IGNORE INTO board_run_namespaces (run_id, item_id, claimed_at, purged_at)
+SELECT lease_run_id, id, COALESCE(claimed_at, updated_at), NULL
+FROM work_items w
+WHERE lease_run_id IS NOT NULL AND lease_run_id <> ''
+  AND NOT EXISTS (
+      SELECT 1 FROM board_run_namespaces n WHERE n.run_id = w.lease_run_id
+  )
+"""
+
+
+def _backfill_run_ledger(conn: sqlite3.Connection) -> None:
+    """Populate the scratch ledger, writing only when a read says it is needed."""
+    # An EMPTY ledger is not enough to justify the write: a board that has never
+    # been claimed has an empty ledger forever, so guarding on emptiness alone left
+    # every open of such a board taking the write lock on a zero-row INSERT — the
+    # exact starvation this function exists to remove. Require an eligible historical
+    # claim as well; the statement keeps its own `NOT EXISTS` for atomicity.
+    needs_audit_backfill = conn.execute(
+        "SELECT EXISTS("
+        "  SELECT 1 FROM transitions"
+        "  WHERE from_state='planned' AND to_state='running'"
+        "    AND note='claimed' AND actor <> ''"
+        ") AND NOT EXISTS(SELECT 1 FROM board_run_namespaces)"
+    ).fetchone()[0]
+    if needs_audit_backfill:
+        conn.execute(_BACKFILL_LEDGER_FROM_AUDIT)
+    unledgered_lease = conn.execute(
+        "SELECT EXISTS("
+        "  SELECT 1 FROM work_items w"
+        "  WHERE w.lease_run_id IS NOT NULL AND w.lease_run_id <> ''"
+        "    AND NOT EXISTS ("
+        "      SELECT 1 FROM board_run_namespaces n WHERE n.run_id = w.lease_run_id"
+        "    )"
+        ")"
+    ).fetchone()[0]
+    if unledgered_lease:
+        conn.execute(_BACKFILL_LEDGER_FROM_LEASES)
+
+#: The audit note ``recover_stale_running`` stamps; ``board stats`` counts these to
+#: surface duplicate-work risk (items that had to be reclaimed from a dead run).
+_STALE_RECLAIM_NOTE = "stale-claim recovery"
+
+# Column order for INSERT/row-mapping — kept in one place so the two stay in sync.
+_COLUMNS = (
+    "id", "goal", "task", "state", "owner_agent", "inputs", "outputs", "evidence",
+    "handoff", "human_required", "blocked_reason", "depends_on", "lease_run_id",
+    "claimed_at", "created_at", "updated_at",
+)
+
+
+# ── Board store ──────────────────────────────────────────────────────────────
+
+
+class Board:
+    """The SQLite-backed work-board. The dispatch + system-of-record core.
+
+    Concurrency model: opened in **autocommit** mode (``isolation_level=None``) so
+    writers issue an explicit ``BEGIN IMMEDIATE`` (a RESERVED lock taken up front),
+    making :meth:`claim` / :meth:`next_runnable` an atomic compare-and-swap — two
+    ``syncmill board run`` processes against one db can never both claim the same
+    ``planned`` item. ``busy_timeout`` lets the loser wait for the winner's commit
+    rather than erroring. WAL keeps readers (``board list``/``show``, the future
+    dashboard) non-blocking against a writer.
+
+    ``now`` is injectable (like the circuit breaker) so tests can drive the
+    stale-claim clock deterministically.
+    """
+
+    def __init__(
+        self,
+        db_path: str,
+        *,
+        now: Callable[[], float] = time.time,
+        lease_timeout_seconds: int = 1800,
+        stall_seconds: int = 3600,
+        busy_timeout_ms: int = 5000,
+    ):
+        require_supported_platform()
+        self._now = now
+        self._lease_timeout = max(1, lease_timeout_seconds)
+        self._stall_seconds = max(1, stall_seconds)
+        self._busy_timeout_ms = int(busy_timeout_ms)
+        try:
+            # expanduser() is INSIDE the try: it raises RuntimeError (NOT an OSError)
+            # when ~ can't resolve because no home dir is set (cron/systemd), so a
+            # narrow catch would let that escape unwrapped — and `Board.__init__`'s
+            # contract is that it raises ONLY BoardError (build_board's sole caller,
+            # `serve`, catches just that; a stray RuntimeError would crash the gateway
+            # and skip its memory-close finally).
+            path = Path(db_path).expanduser()
+            _prepare_private_board(path)
+            # isolation_level=None → autocommit; we drive BEGIN IMMEDIATE/COMMIT by
+            # hand for the atomic claims. row_factory=Row for name-based access.
+            self._conn = sqlite3.connect(str(path), isolation_level=None)
+            self._db_path = path.resolve()
+            self._conn.row_factory = sqlite3.Row
+            self._conn.execute(f"PRAGMA busy_timeout={int(busy_timeout_ms)}")
+            self._conn.execute("PRAGMA journal_mode=WAL")
+            self._conn.executescript(_SCHEMA)
+            _add_missing_columns(self._conn)
+            _backfill_run_ledger(self._conn)
+            _tighten_board_files(path)
+        except (sqlite3.Error, OSError, RuntimeError, ValueError) as exc:
+            # A corrupt / non-sqlite / unwritable / unresolvable db is fatal for a
+            # load-bearing store — raise rather than degrade (the whole point of the
+            # board). OSError covers an unwritable/missing parent dir (mkdir / connect);
+            # sqlite3.Error covers a corrupt or non-sqlite file; RuntimeError covers an
+            # unresolvable `~` (no home dir); ValueError covers a db path carrying a
+            # null byte, which sqlite3.connect rejects before it is ever a db error —
+            # `Board.__init__`'s documented contract is that it raises ONLY BoardError,
+            # so every way a path can be rejected has to land here. `connect()` is lazy
+            # (it succeeds before the first PRAGMA/schema access surfaces a corrupt
+            # file), so close the partial connection here rather than leaking its fd.
+            conn = getattr(self, "_conn", None)
+            if conn is not None:
+                try:
+                    conn.close()
+                except sqlite3.Error:
+                    pass
+            raise BoardError(f"failed to open board at {db_path}: {exc}") from exc
+
+    # ── writes (atomic) ──────────────────────────────────────────────────────
+
+    @property
+    def db_path(self) -> Path:
+        """Canonical path, used to open thread-local lease-renewal connections."""
+        return self._db_path
+
+    @property
+    def lease_timeout_seconds(self) -> int:
+        return self._lease_timeout
+
+    @property
+    def stall_seconds(self) -> int:
+        return self._stall_seconds
+
+    def new_connection(self) -> "Board":
+        """Open an equivalent connection in the calling thread."""
+        return Board(
+            str(self._db_path),
+            now=self._now,
+            lease_timeout_seconds=self._lease_timeout,
+            stall_seconds=self._stall_seconds,
+            busy_timeout_ms=self._busy_timeout_ms,
+        )
+
+    def renew_claim(self, item_id: str, run_id: str) -> bool:
+        """Lease-fenced heartbeat for a currently running item."""
+        try:
+            cur = self._conn.execute(
+                "UPDATE work_items SET claimed_at=? "
+                "WHERE id=? AND state=? AND lease_run_id=?",
+                (self._now(), item_id, WorkState.RUNNING.value, run_id),
+            )
+            return cur.rowcount == 1
+        except Exception as exc:
+            raise BoardError(f"renew claim failed: {exc}") from exc
+
+    def add(
+        self,
+        task: str,
+        *,
+        goal: str = "",
+        depends_on: list[str] | None = None,
+        human_required: bool = False,
+        inputs: list[str] | None = None,
+        item_id: str | None = None,
+    ) -> WorkItem:
+        """Insert a new ``planned`` item and return it (with an audit row)."""
+        now = self._now()
+        item = WorkItem(
+            id=item_id or str(uuid.uuid4()),
+            goal=goal,
+            task=task,
+            state=WorkState.PLANNED,
+            inputs=list(inputs or []),
+            human_required=human_required,
+            depends_on=list(depends_on or []),
+            created_at=now,
+            updated_at=now,
+        )
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            self._conn.execute(
+                f"INSERT INTO work_items ({','.join(_COLUMNS)}) "
+                f"VALUES ({','.join('?' for _ in _COLUMNS)})",
+                _item_to_row(item),
+            )
+            self._insert_transition(item.id, None, item.state.value, "human", "created", now)
+            self._conn.execute("COMMIT")
+        except Exception as exc:
+            # Broad (matching next_runnable/apply_update/transition/recover/add_decision):
+            # roll back the open BEGIN IMMEDIATE on ANY error so the RESERVED write lock
+            # is never leaked. _item_to_row's json.dumps can raise a NON-sqlite TypeError
+            # on an unserializable input AFTER BEGIN IMMEDIATE — a narrow `sqlite3.Error`
+            # catch would leak the lock and the next write fails with "cannot start a
+            # transaction within a transaction" (codex-found blocker).
+            self._safe_rollback()
+            raise BoardError(f"failed to add item: {exc}") from exc
+        return item
+
+    def import_review_candidates(
+        self,
+        specs: list[ReviewItemSpec],
+        *,
+        goal: str,
+    ) -> ReviewImportResult:
+        """Atomically insert Tracegraph findings as human-only ``review`` items.
+
+        Identity is the deterministic UUID carried by each spec. Re-importing an
+        existing finding never reopens or rewrites it, even after human resolution.
+        A UUID collision with different immutable provenance aborts the whole batch.
+        """
+        now = self._now()
+        imported = 0
+        skipped = 0
+        goal_kept = 0
+        item_ids: list[str] = []
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            for spec in specs:
+                item = WorkItem(
+                    id=spec.item_id,
+                    goal=goal,
+                    task=spec.task,
+                    state=WorkState.REVIEW,
+                    inputs=list(spec.inputs),
+                    evidence=[
+                        Evidence(
+                            kind="tracegraph",
+                            ref=spec.artifact_digest,
+                            passed=False,
+                            at=now,
+                            by="tracegraph",
+                        )
+                    ],
+                    human_required=True,
+                    created_at=now,
+                    updated_at=now,
+                )
+                cur = self._conn.execute(
+                    f"INSERT INTO work_items ({','.join(_COLUMNS)}) "
+                    f"VALUES ({','.join('?' for _ in _COLUMNS)}) "
+                    "ON CONFLICT(id) DO NOTHING",
+                    _item_to_row(item),
+                )
+                if cur.rowcount == 1:
+                    imported += 1
+                    self._insert_transition(
+                        item.id,
+                        None,
+                        WorkState.REVIEW.value,
+                        "tracegraph-import",
+                        "imported review candidate",
+                        now,
+                    )
+                else:
+                    row = self._conn.execute(
+                        "SELECT * FROM work_items WHERE id=?", (item.id,)
+                    ).fetchone()
+                    existing = _row_to_item(row)
+                    if not _same_review_provenance(existing, item):
+                        raise BoardError(
+                            f"review-candidate provenance collision for item {item.id}"
+                        )
+                    skipped += 1
+                    if existing.goal != goal:
+                        goal_kept += 1
+                item_ids.append(item.id)
+            self._conn.execute("COMMIT")
+            return ReviewImportResult(imported, skipped, tuple(item_ids), goal_kept)
+        except BoardError:
+            self._safe_rollback()
+            raise
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(f"failed to import review candidates: {exc}") from exc
+
+    def claim(self, item_id: str, run_id: str) -> WorkItem | None:
+        """Atomically claim a specific ``planned`` item for ``run_id`` (CAS
+        ``planned → running``). Returns the claimed item, or ``None`` if it doesn't
+        exist or isn't ``planned`` (already claimed/done/blocked/etc.).
+
+        The atomic, every-path no-duplicate-work guard: under ``BEGIN IMMEDIATE``
+        the second concurrent claimer blocks until the first commits, then reads
+        ``running`` and returns ``None``."""
+        return self._claim_where("id=? AND state=?",
+                                 (item_id, WorkState.PLANNED.value), run_id)
+
+    def next_runnable(self, run_id: str, goal: str | None = None) -> WorkItem | None:
+        """Atomically claim the next dispatchable item for ``run_id``, or ``None``.
+
+        Dispatchable = ``planned``, not ``human_required``, and every ``depends_on``
+        item is ``done``. Items are considered in FIFO order (``created_at``). The
+        whole select-then-claim runs in one ``BEGIN IMMEDIATE`` transaction, so it
+        is as atomic as :meth:`claim`.
+
+        A ``goal`` scopes the claim to items with exactly that goal (the
+        ``board run --goal`` filter, Phase 4) — just an extra WHERE clause inside
+        the same transaction, so atomicity is unchanged. ``None`` (the default)
+        considers every item, exactly as before."""
+        where = "state=? AND human_required=0"
+        params: list = [WorkState.PLANNED.value]
+        if goal is not None:
+            where += " AND goal=?"
+            params.append(goal)
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            rows = self._conn.execute(
+                f"SELECT * FROM work_items WHERE {where} ORDER BY created_at, rowid",
+                params,
+            ).fetchall()
+            # LAZY, per-candidate done lookups — everything here runs under
+            # the BEGIN IMMEDIATE RESERVED lock, so the work must stay
+            # proportional to the candidates actually EXAMINED: the scan stops
+            # at the first satisfied item (a runnable FIFO head costs zero
+            # queries when it has no dependencies, one bounded query when it
+            # does), and each lookup asks only for that candidate's
+            # still-unknown dep ids — never a full done-history scan, never
+            # the tail's dependencies. Cached across candidates so a shared
+            # dep is fetched once; chunked IN lists because SQLite caps bound
+            # parameters (999 on older builds). Same transaction, so the
+            # snapshot matches what per-dep reads would see.
+            done_ids: set = set()
+            looked_up: set = set()
+
+            def _deps_done(deps: list) -> bool:
+                unknown = [d for d in deps if d not in looked_up]
+                for start in range(0, len(unknown), 500):
+                    chunk = unknown[start : start + 500]
+                    marks = ",".join("?" * len(chunk))
+                    done_ids.update(
+                        r["id"]
+                        for r in self._conn.execute(
+                            "SELECT id FROM work_items WHERE state=? "
+                            f"AND id IN ({marks})",
+                            (WorkState.DONE.value, *chunk),
+                        )
+                    )
+                    looked_up.update(chunk)
+                return self._deps_satisfied(deps, done_ids)
+
+            chosen = next(
+                (r for r in rows if _deps_done(json.loads(r["depends_on"]))),
+                None,
+            )
+            if chosen is None:
+                self._conn.execute("COMMIT")  # read-only; nothing to dispatch
+                return None
+            item = self._stamp_running(chosen, run_id)
+            self._conn.execute("COMMIT")
+            return item
+        except Exception as exc:
+            # Broad on purpose: a non-sqlite error mid-transaction (e.g. a corrupt
+            # `depends_on` JSON failing `json.loads` above → ValueError) must still
+            # roll back the open BEGIN IMMEDIATE — otherwise the RESERVED lock leaks
+            # and the next op fails with "cannot start a transaction within a
+            # transaction". Surfaces as BoardError, like get()/list() already do.
+            self._safe_rollback()
+            raise BoardError(f"next_runnable failed: {exc}") from exc
+
+    def apply_update(
+        self,
+        item_id: str,
+        parsed: dict,
+        result: TaskResult,
+        actor: str,
+        run_id: str | None = None,
+    ) -> tuple[WorkItem, bool]:
+        """Record a finished run back onto the item, in one transaction.
+
+        Returns ``(item, applied)``: ``applied`` is ``True`` when this run's write
+        took effect, ``False`` when the lease fence dropped it (below). The caller
+        (``run_item``) gates its follow-on global-``shared`` cross-link on
+        ``applied`` so a superseded run never publishes discarded output.
+
+        Merges the agent's optional parsed board block with inferred defaults —
+        ``result.files_changed`` ∪ ``parsed['outputs']`` → ``outputs``; a
+        ``GateReport`` (``result.gate``) → one :class:`Evidence` row; the run's
+        status + the agent's advisory ``parsed['state']`` → the next state — and
+        stamps ``owner_agent`` (record-only). ``blocked_reason`` is cleared on any
+        non-blocked resolution, so a re-run that succeeds doesn't carry a stale
+        reason from a prior block.
+
+        **Lease-fenced** when ``run_id`` is given (the ``run_item`` path): the
+        write is a compare-and-swap ``WHERE id=? AND state='running' AND
+        lease_run_id=?``. If a slow run's item was reclaimed by
+        ``recover_stale_running`` and re-dispatched to another runner while it ran,
+        the fence matches 0 rows → this stale write is DROPPED (it neither clobbers
+        the new owner's state nor reverts a verified ``done``), and the current item
+        is returned untouched WITH ``applied=False`` so the caller can suppress any
+        follow-on side effect (the global-``shared`` summary). Without ``run_id`` the
+        write is unfenced (for non-dispatch callers/tests) and ``applied`` is True.
+
+        **Advisory, never raises on a bad agent request** (decision #5): an agent
+        that requests ``state:done`` without passing evidence is CLAMPED to
+        ``review`` (+ an audit note), so a successful run is never turned into
+        ``blocked`` by an invalid advisory field. A FAILED run (agent failure or a
+        gate rejection) maps to ``blocked`` with the error as the reason. Only a
+        genuine sqlite error raises :class:`BoardError`."""
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            row = self._conn.execute(
+                "SELECT * FROM work_items WHERE id=?", (item_id,)
+            ).fetchone()
+            if row is None:
+                raise BoardError(f"no such item: {item_id}")
+            item = _row_to_item(row)
+            now = self._now()
+
+            outputs = _merge_unique(item.outputs, parsed.get("outputs", []))
+            outputs = _merge_unique(outputs, list(result.files_changed))
+
+            evidence = list(item.evidence)
+            run_evidence: list[Evidence] = []  # only THIS run's verification
+            if result.gate is not None:
+                # A passing gate is objective verification; a failing gate is the
+                # evidence the work did NOT verify. Agents can't self-certify done.
+                ev = Evidence(
+                    kind="gate", ref=result.gate.summary(),
+                    passed=result.gate.passed, at=now, by=result.agent_id,
+                )
+                evidence.append(ev)
+                run_evidence.append(ev)
+
+            handoff = parsed.get("handoff", item.handoff)
+            human_required = bool(parsed.get("human_required", item.human_required))
+            blocked_reason = ""  # cleared unless we resolve to blocked (no stale reason)
+            requested = parsed.get("state")
+
+            if result.status == TaskStatus.COMPLETED:
+                # Gate the agent's advisory `done` on THIS run's verification only —
+                # stale passing evidence from an earlier (now-discarded) run must not
+                # certify the current work ("done AND verified" = the CURRENT work is
+                # verified). The full accumulated `evidence` is still persisted below
+                # and still backs the human review→done promotion via `transition`.
+                target, note = _resolve_completed_state(requested, run_evidence)
+                if target == WorkState.BLOCKED:
+                    blocked_reason = (
+                        str(parsed.get("blocked_reason", "")) or "agent reported blocked"
+                    )
+                    human_required = True  # a blocked item needs a human to unblock
+            else:
+                target = WorkState.BLOCKED
+                blocked_reason = result.error or f"run failed (exit {result.exit_code})"
+                human_required = True
+                note = "run failed"
+
+            set_params = [
+                target.value, result.agent_id, json.dumps(outputs),
+                _dump_evidence(evidence), handoff, int(human_required),
+                blocked_reason, now,
+            ]
+            where, where_params = "id=?", [item_id]
+            if run_id is not None:
+                # Lease fence: only the run that still owns the running claim writes.
+                where += " AND state=? AND lease_run_id=?"
+                where_params += [WorkState.RUNNING.value, run_id]
+            cur = self._conn.execute(
+                "UPDATE work_items SET state=?, owner_agent=?, outputs=?, evidence=?, "
+                "handoff=?, human_required=?, blocked_reason=?, lease_run_id=NULL, "
+                f"claimed_at=NULL, updated_at=? WHERE {where}",
+                set_params + where_params,
+            )
+            if run_id is not None and cur.rowcount == 0:
+                # Lost lease: the item's state or lease owner changed while we ran
+                # (a stale reclaim + re-dispatch is the usual cause, a manual
+                # transition does it too).
+                # Drop this stale write entirely (record nothing) so we never clobber
+                # the new owner or revert a verified state.
+                self._conn.execute("COMMIT")
+                logger.warning(
+                    "board: dropping stale apply_update for %s — run %s no longer "
+                    "owns the lease (its state or lease owner changed)", item_id, run_id,
+                )
+                return self.get(item_id), False  # type: ignore[return-value]
+            self._insert_transition(item_id, item.state.value, target.value, actor, note, now)
+            self._conn.execute("COMMIT")
+            return self.get(item_id), True  # type: ignore[return-value]
+        except BoardError:
+            self._safe_rollback()
+            raise
+        except Exception as exc:
+            # Broad: roll back the open transaction on ANY error (incl. a ValueError
+            # from a corrupt row via _row_to_item), never leaking the write lock.
+            self._safe_rollback()
+            raise BoardError(f"apply_update failed: {exc}") from exc
+
+    def transition(
+        self,
+        item_id: str,
+        to_state: str | None,
+        *,
+        actor: str,
+        note: str = "",
+        evidence: list[Evidence] | Evidence | None = None,
+        human_required: bool | None = None,
+        blocked_reason: str | None = None,
+        run_id: str | None = None,
+    ) -> WorkItem:
+        """Change an item's state, with the ``done`` gate enforced.
+
+        A transition **to** ``done`` requires the item to already carry, or to be
+        given here, at least one passing :class:`Evidence` row OR a human sign-off
+        (``Evidence{kind:"human"}``); otherwise it raises :class:`BoardError` — a
+        bare ``board update ID --state done`` with nothing to back it is rejected.
+        ``evidence`` rows are appended (counting toward the gate); ``human_required``
+        is set when not ``None``.
+
+        ``to_state=None`` is an annotate-only update: the target is the item's CURRENT
+        state, resolved from THIS in-transaction read (never a stale pre-transaction
+        read), so a concurrent claim can't be clobbered by a stale annotate target.
+        The done gate only fires for an actual move to ``done``.
+
+        ``blocked_reason`` is recorded on the row only for a move TO ``blocked``
+        (any other target clears it, mirroring ``apply_update``); omitted, a move to
+        ``blocked`` keeps the reason the row already carried.
+
+        ``run_id`` lease-fences the write (the crash-block path): when given, the
+        UPDATE only matches while the item is still ``running`` under that lease, so a
+        stale crashed run can't clobber a re-dispatched owner or revert a verified
+        state — a 0-row match drops the write, exactly like ``apply_update``."""
+        if to_state is not None and to_state not in _STATES:
+            raise BoardError(f"unknown state: {to_state!r}")
+        new_rows = (
+            [] if evidence is None
+            else [evidence] if isinstance(evidence, Evidence)
+            else list(evidence)
+        )
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            row = self._conn.execute(
+                "SELECT * FROM work_items WHERE id=?", (item_id,)
+            ).fetchone()
+            if row is None:
+                raise BoardError(f"no such item: {item_id}")
+            item = _row_to_item(row)
+            target = item.state if to_state is None else WorkState(to_state)
+            # `running` is owned by the claim lease, never set by hand: a manual move
+            # INTO running from another state would mint a lease-less, undispatchable
+            # item (next_runnable/claim both gate on `planned`). Only a same-state
+            # annotate of an ALREADY-running item reaches the lease-preserving branch.
+            if target == WorkState.RUNNING and item.state != WorkState.RUNNING:
+                raise BoardError(
+                    f"cannot move item {item_id} to 'running' by hand — it is claimed "
+                    f"by `board run`"
+                )
+            merged_evidence = item.evidence + new_rows
+            if target == WorkState.DONE and not _has_verification(merged_evidence):
+                raise BoardError(
+                    f"cannot mark item {item_id} done without verification — attach "
+                    f"passing evidence (--evidence) or a human sign-off (--sign-off)"
+                )
+            now = self._now()
+            hr = item.human_required if human_required is None else human_required
+            # Leaving blocked drops the stale reason (mirrors apply_update); a move TO
+            # blocked takes the caller's reason when given, else keeps whatever reason
+            # the row already carried. Without the parameter a crash-block's cause was
+            # visible only in the audit note, so `board show` printed an empty
+            # `blocked:` line for exactly the items an operator has to triage.
+            if target != WorkState.BLOCKED:
+                reason = ""
+            elif blocked_reason is not None:
+                reason = blocked_reason
+            else:
+                reason = item.blocked_reason
+            where, where_params = "id=?", [item_id]
+            if run_id is not None:
+                # Lease fence: only the run that still owns the running claim writes.
+                where += " AND state=? AND lease_run_id=?"
+                where_params += [WorkState.RUNNING.value, run_id]
+            if target == WorkState.RUNNING:
+                # Same-state annotate of a RUNNING item must PRESERVE the lease —
+                # nulling it would let recover_stale_running treat the live item as
+                # abandoned and re-dispatch it (duplicate work).
+                cur = self._conn.execute(
+                    "UPDATE work_items SET state=?, evidence=?, human_required=?, "
+                    f"blocked_reason=?, updated_at=? WHERE {where}",
+                    [target.value, _dump_evidence(merged_evidence), int(hr),
+                     reason, now, *where_params],
+                )
+            else:
+                # Leaving running → the claim is consumed; clear the lease.
+                cur = self._conn.execute(
+                    "UPDATE work_items SET state=?, evidence=?, human_required=?, "
+                    "blocked_reason=?, lease_run_id=NULL, claimed_at=NULL, "
+                    f"updated_at=? WHERE {where}",
+                    [target.value, _dump_evidence(merged_evidence), int(hr),
+                     reason, now, *where_params],
+                )
+            if run_id is not None and cur.rowcount == 0:
+                # Lost lease: the item's state or lease owner changed while we ran
+                # (a reclaim + re-dispatch, or simply having already left running) —
+                # drop this stale write, recording nothing.
+                self._conn.execute("COMMIT")
+                logger.warning(
+                    "board: dropping stale transition for %s — run %s no longer owns "
+                    "the lease (its state or lease owner changed)", item_id, run_id,
+                )
+                return self.get(item_id)  # type: ignore[return-value]
+            self._insert_transition(
+                item_id, item.state.value, target.value, actor,
+                note or ("annotated" if target == item.state else ""), now,
+            )
+            self._conn.execute("COMMIT")
+            return self.get(item_id)  # type: ignore[return-value]
+        except BoardError:
+            self._safe_rollback()
+            raise
+        except Exception as exc:
+            # Broad: roll back on ANY error (incl. a ValueError from a corrupt row)
+            # so the open transaction / write lock is never leaked.
+            self._safe_rollback()
+            raise BoardError(f"transition failed: {exc}") from exc
+
+    def recover_stale_running(self, lease_timeout: int | None = None) -> int:
+        """Reclaim items stuck in ``running`` past the lease back to ``planned``.
+
+        A ``kill -9`` between :meth:`claim` and :meth:`apply_update` would strand an
+        item in ``running`` forever (``next_runnable`` skips ``running`` items). This
+        is the analogue of ``cleanup_orphaned_worktrees`` /
+        ``session._sweep_stale_session_dirs``: an item whose ``claimed_at`` is older
+        than the lease (or missing) is moved back to ``planned`` with an audit row,
+        so it can be redispatched. Returns the count reclaimed."""
+        timeout = self._lease_timeout if lease_timeout is None else max(1, lease_timeout)
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            now = self._now()
+            cutoff = now - timeout
+            rows = self._conn.execute(
+                "SELECT id, claimed_at, lease_run_id FROM work_items WHERE state=?",
+                (WorkState.RUNNING.value,),
+            ).fetchall()
+            reclaimed = 0
+            for r in rows:
+                ca = r["claimed_at"]
+                if ca is not None and ca > cutoff:
+                    continue  # still within its lease
+                # Stamp WHEN the lease was taken away, in the same transaction:
+                # a reclaim means "presumed dead", and the scratch collector uses
+                # this to give a merely-slow run a grace period before deleting
+                # the namespace it is still reading and writing.
+                self._conn.execute(
+                    "UPDATE board_run_namespaces SET reclaimed_at=? WHERE run_id=?",
+                    (now, r["lease_run_id"]),
+                )
+                self._conn.execute(
+                    "UPDATE work_items SET state=?, lease_run_id=NULL, claimed_at=NULL, "
+                    "updated_at=? WHERE id=? AND state=?",
+                    (WorkState.PLANNED.value, now, r["id"], WorkState.RUNNING.value),
+                )
+                self._insert_transition(
+                    r["id"], WorkState.RUNNING.value, WorkState.PLANNED.value,
+                    "system", _STALE_RECLAIM_NOTE, now,
+                )
+                reclaimed += 1
+            self._conn.execute("COMMIT")
+            return reclaimed
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(f"recover_stale_running failed: {exc}") from exc
+
+    def add_decision(
+        self,
+        text: str,
+        *,
+        scope: str = "",
+        supersedes: str | None = None,
+        decision_id: str | None = None,
+    ) -> Decision:
+        """Record a team :class:`Decision` (Phase 2), atomically retiring the one it
+        supersedes (if any) in the same transaction.
+
+        ``scope=""`` is GLOBAL (applies to every item); a goal string scopes it to
+        that goal. ``supersedes`` is the id of an ACTIVE decision IN THE SAME SCOPE
+        this replaces — it is marked superseded (and so drops out of
+        :meth:`active_decisions`) the moment the new one lands, so a goal never carries
+        two contradictory live decisions. The superseded decision must share the new
+        one's ``scope`` (a replacement retires the thing it replaces, in place) — a
+        cross-scope ``supersedes`` is a caller mistake (it would silently retire an
+        UNRELATED goal's decision while inserting here), so it raises :class:`BoardError`.
+        Superseding a missing or already-retired decision likewise raises
+        :class:`BoardError` (a stale id is a caller mistake, not a silent no-op), and in
+        every error case the new decision is NOT inserted. ``text`` is required (an
+        empty decision is meaningless)."""
+        if not text or not text.strip():
+            raise BoardError("a decision needs non-empty text")
+        now = self._now()
+        dec = Decision(
+            id=decision_id or str(uuid.uuid4()),
+            text=text.strip(),
+            scope=scope,
+            created_at=now,
+        )
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            if supersedes is not None:
+                # Same-scope CAS: only retire a decision that shares the new one's
+                # scope. A 0-row match means the target is missing, already retired,
+                # OR scoped elsewhere — distinguish them for a clear error (and never
+                # silently retire another goal's decision via a cross-scope id).
+                cur = self._conn.execute(
+                    "UPDATE decisions SET superseded_by=?, superseded_at=? "
+                    "WHERE id=? AND superseded_by IS NULL AND scope=?",
+                    (dec.id, now, supersedes, scope),
+                )
+                if cur.rowcount == 0:
+                    row = self._conn.execute(
+                        "SELECT scope, superseded_by FROM decisions WHERE id=?",
+                        (supersedes,),
+                    ).fetchone()
+                    if row is None:
+                        reason = "no such decision"
+                    elif row["superseded_by"] is not None:
+                        reason = "it is already superseded"
+                    else:
+                        reason = (
+                            f"it is scoped to {row['scope']!r}, not {scope!r} — "
+                            "supersede only retires a decision in the same scope"
+                        )
+                    raise BoardError(f"cannot supersede {supersedes}: {reason}")
+            self._conn.execute(
+                "INSERT INTO decisions (id, text, scope, created_at, superseded_by, "
+                "superseded_at) VALUES (?,?,?,?,?,?)",
+                (dec.id, dec.text, dec.scope, dec.created_at, None, None),
+            )
+            self._conn.execute("COMMIT")
+            return dec
+        except BoardError:
+            self._safe_rollback()
+            raise
+        except Exception as exc:
+            # Broad (matching next_runnable/apply_update/transition/recover): roll back
+            # the open BEGIN IMMEDIATE on ANY error so the RESERVED write lock is never
+            # leaked — the documented txn-safety invariant, held by construction.
+            self._safe_rollback()
+            raise BoardError(f"add_decision failed: {exc}") from exc
+
+    # ── reads ────────────────────────────────────────────────────────────────
+
+    def get(self, item_id: str) -> WorkItem | None:
+        """The item, or ``None`` if no such id.
+
+        A malformed id (not a uuid) is treated as not-found and returns ``None``
+        WITHOUT a query — the single-coupling guard for the read-only gateway's
+        ``board_get`` (mirrors ``SyncmillMemory.get_shared``): every real
+        :class:`WorkItem` id is a ``uuid4``, so an unparseable id is a client typo,
+        never a row, and must not reach a guessed/probing lookup."""
+        if not _is_valid_item_id(item_id):
+            return None
+        try:
+            row = self._conn.execute(
+                "SELECT * FROM work_items WHERE id=?", (item_id,)
+            ).fetchone()
+            # _row_to_item is inside the try (and ValueError is caught) so a
+            # corrupt/out-of-enum `state` from a hand-edited db surfaces as a
+            # contracted BoardError, not a raw ValueError traceback.
+            return _row_to_item(row) if row is not None else None
+        except (sqlite3.Error, ValueError) as exc:
+            raise BoardError(f"get failed: {exc}") from exc
+
+    def list(self, state: str | None = None, goal: str | None = None) -> list[WorkItem]:
+        """All items, optionally filtered by ``state`` and/or ``goal`` (FIFO order)."""
+        clauses, params = [], []
+        if state is not None:
+            if state not in _STATES:
+                raise BoardError(f"unknown state: {state!r}")
+            clauses.append("state=?")
+            params.append(state)
+        if goal is not None:
+            clauses.append("goal=?")
+            params.append(goal)
+        where = (" WHERE " + " AND ".join(clauses)) if clauses else ""
+        try:
+            rows = self._conn.execute(
+                f"SELECT * FROM work_items{where} ORDER BY created_at, rowid", params
+            ).fetchall()
+            return [_row_to_item(r) for r in rows]  # ValueError (bad state) → BoardError
+        except (sqlite3.Error, ValueError) as exc:
+            raise BoardError(f"list failed: {exc}") from exc
+
+    def list_recent(
+        self, *, state: str | None = None, goal: str | None = None, limit: int
+    ) -> list[WorkItem]:
+        """The newest ``limit`` items, NEWEST first, sorted and bounded in SQL.
+
+        ``created_at DESC, rowid DESC`` is exactly ``reversed`` of :meth:`list`'s
+        ``created_at, rowid`` FIFO, so the order and the same-timestamp tie-break
+        match ``list(reversed(self.list(...)))[:limit]`` — but only ``limit``
+        rows are fetched and converted (#167: the MCP ``board_list`` tool used
+        to materialize the whole board to answer ``limit=1``). Filters apply
+        before the limit. ``limit`` must be an int ≥ 1; clamping a client value
+        is the caller's job, a nonsensical bound is refused.
+        """
+        if isinstance(limit, bool) or not isinstance(limit, int) or limit < 1:
+            raise BoardError(f"limit must be a positive integer, got {limit!r}")
+        clauses, params = [], []
+        if state is not None:
+            if state not in _STATES:
+                raise BoardError(f"unknown state: {state!r}")
+            clauses.append("state=?")
+            params.append(state)
+        if goal is not None:
+            clauses.append("goal=?")
+            params.append(goal)
+        where = (" WHERE " + " AND ".join(clauses)) if clauses else ""
+        try:
+            rows = self._conn.execute(
+                f"SELECT * FROM work_items{where} "
+                "ORDER BY created_at DESC, rowid DESC LIMIT ?",
+                [*params, limit],
+            ).fetchall()
+            return [_row_to_item(r) for r in rows]
+        except (sqlite3.Error, ValueError) as exc:
+            raise BoardError(f"list failed: {exc}") from exc
+
+    def collectible_board_run_ids(self, *, limit: int = 100) -> list[str]:
+        """Oldest unpurged scratch owners that no longer hold a live lease.
+
+        Ledger insertion and lease stamping commit in the same claim transaction,
+        so this single SQLite snapshot replaces the old backend-enumeration then
+        lease-read dance without opening a concurrent-claim deletion race.
+
+        "Holds no lease" alone is not enough for a run whose lease was taken by
+        ``recover_stale_running``: a reclaim means presumed dead, and a run that
+        is merely SLOW is still reading and writing its scratch namespace.
+        Deleting it there silently empties a live pipeline's stage-to-stage
+        handoff with nothing degraded to show for it (the delete succeeded). So a
+        reclaimed run gets one further lease timeout of grace. A run still alive
+        past that is the pre-existing accepted residue — its board write is
+        fence-dropped anyway, memory is advisory, and the namespace is recreated
+        by its next write. A run that left ``running`` normally has no
+        ``reclaimed_at`` and is collectible immediately, as before.
+        """
+        if limit <= 0:
+            return []
+        now = self._now()
+        grace_cutoff = now - self._lease_timeout
+        try:
+            rows = self._conn.execute(
+                "SELECT n.run_id FROM board_run_namespaces AS n "
+                "WHERE n.purged_at IS NULL "
+                "AND (n.reclaimed_at IS NULL OR n.reclaimed_at <= ?) "
+                # Purge-failure backoff: a row whose purge keeps failing waits
+                # out its scheduled retry instead of head-of-line-blocking the
+                # sweep (see record_board_run_purge_failures).
+                "AND (n.next_attempt_at IS NULL OR n.next_attempt_at <= ?) "
+                "AND NOT EXISTS ("
+                "SELECT 1 FROM work_items AS w WHERE w.state=? "
+                "AND w.lease_run_id=n.run_id) "
+                "ORDER BY n.claimed_at, n.rowid LIMIT ?",
+                (grace_cutoff, now, WorkState.RUNNING.value, limit),
+            ).fetchall()
+            return [r["run_id"] for r in rows]
+        except sqlite3.Error as exc:
+            raise BoardError(f"collectible_board_run_ids failed: {exc}") from exc
+
+    def mark_board_run_namespaces_purged(self, run_ids: Iterable[str]) -> int:
+        """Tombstone successfully processed scratch namespaces, atomically."""
+        ids = list(dict.fromkeys(rid for rid in run_ids if rid))
+        if not ids:
+            return 0
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            now = self._now()
+            updated = 0
+            for run_id in ids:
+                # A successful purge also RESETS the failure backoff: earlier
+                # failures are stale history now, and carrying them into a
+                # reactivated row would make its next (unrelated) failure count
+                # as consecutive — inheriting quarantine-grade backoff at once.
+                cur = self._conn.execute(
+                    "UPDATE board_run_namespaces "
+                    "SET purged_at=?, failed_attempts=NULL, next_attempt_at=NULL "
+                    "WHERE run_id=? AND purged_at IS NULL",
+                    (now, run_id),
+                )
+                updated += cur.rowcount
+            self._conn.execute("COMMIT")
+            return updated
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(f"mark_board_run_namespaces_purged failed: {exc}") from exc
+
+    #: Exponential backoff for a namespace whose purge failed: first retry after
+    #: the base, doubling per consecutive failure, capped. The cap keeps a
+    #: permanently poisoned row (an operator-fixable condition — a symlink, an
+    #: unmounted root) retried a few times a day rather than never, so a fix
+    #: lands without manual intervention.
+    _PURGE_BACKOFF_BASE_SECONDS = 60.0
+    _PURGE_BACKOFF_CAP_SECONDS = 6 * 3600.0
+    #: After this many consecutive failures the row is loudly flagged as
+    #: quarantined (still retried on the capped schedule — never dropped, since
+    #: only a successful purge may tombstone a namespace).
+    PURGE_QUARANTINE_ATTEMPTS = 5
+
+    def record_board_run_purge_failures(self, run_ids: Iterable[str]) -> list[str]:
+        """Schedule failed purges for exponential-backoff retry, atomically.
+
+        Returns the run ids that just crossed :data:`PURGE_QUARANTINE_ATTEMPTS`
+        (for the caller to warn about). Failure scheduling never tombstones —
+        the fail-closed purge contract (only a proven-complete purge may retire
+        a namespace from collection) is untouched; this only decides WHEN the
+        next attempt happens, so one poisoned row can't consume the whole GC
+        budget every sweep while healthy rows behind it starve.
+        """
+        ids = list(dict.fromkeys(rid for rid in run_ids if rid))
+        if not ids:
+            return []
+        quarantined: list[str] = []
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            now = self._now()
+            for run_id in ids:
+                row = self._conn.execute(
+                    "SELECT failed_attempts FROM board_run_namespaces "
+                    "WHERE run_id=? AND purged_at IS NULL",
+                    (run_id,),
+                ).fetchone()
+                if row is None:
+                    continue
+                attempts = int(row["failed_attempts"] or 0) + 1
+                delay = min(
+                    self._PURGE_BACKOFF_BASE_SECONDS * (2 ** (attempts - 1)),
+                    self._PURGE_BACKOFF_CAP_SECONDS,
+                )
+                self._conn.execute(
+                    "UPDATE board_run_namespaces "
+                    "SET failed_attempts=?, next_attempt_at=? "
+                    "WHERE run_id=? AND purged_at IS NULL",
+                    (attempts, now + delay, run_id),
+                )
+                if attempts == self.PURGE_QUARANTINE_ATTEMPTS:
+                    quarantined.append(run_id)
+            self._conn.execute("COMMIT")
+            return quarantined
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(
+                f"record_board_run_purge_failures failed: {exc}"
+            ) from exc
+
+    def reactivate_board_run_namespace(self, run_id: str) -> bool:
+        """Clear a tombstone after late scoped activity (best-effort caller)."""
+        try:
+            cur = self._conn.execute(
+                "UPDATE board_run_namespaces SET purged_at=NULL "
+                "WHERE run_id=? AND purged_at IS NOT NULL",
+                (run_id,),
+            )
+            return cur.rowcount == 1
+        except sqlite3.Error as exc:
+            raise BoardError(f"reactivate_board_run_namespace failed: {exc}") from exc
+
+    def transitions(self, item_id: str) -> list[dict]:
+        """The append-only audit trail for an item (oldest first)."""
+        try:
+            rows = self._conn.execute(
+                "SELECT from_state, to_state, actor, note, at FROM transitions "
+                "WHERE item_id=? ORDER BY id",
+                (item_id,),
+            ).fetchall()
+        except sqlite3.Error as exc:
+            raise BoardError(f"transitions failed: {exc}") from exc
+        return [dict(r) for r in rows]
+
+    def active_decisions(self, goal: str | None = None) -> list[Decision]:
+        """The active (non-superseded) decisions, oldest-first (Phase 2).
+
+        ``goal=None`` returns every active decision regardless of scope (the full
+        ``board decisions`` view). A ``goal`` string returns the decisions that APPLY
+        to that goal — the GLOBAL ones (``scope=""``) plus those scoped to exactly
+        that goal — which is what ``run_item`` injects into an item's prompt
+        (``goal=item.goal``)."""
+        clauses = ["superseded_by IS NULL"]
+        params: list = []
+        if goal is not None:
+            clauses.append("(scope='' OR scope=?)")
+            params.append(goal)
+        where = " AND ".join(clauses)
+        try:
+            rows = self._conn.execute(
+                "SELECT id, text, scope, created_at, superseded_by, superseded_at "
+                f"FROM decisions WHERE {where} ORDER BY created_at, rowid",
+                params,
+            ).fetchall()
+            return [_row_to_decision(r) for r in rows]
+        except sqlite3.Error as exc:
+            raise BoardError(f"active_decisions failed: {exc}") from exc
+
+    def stats(
+        self, *, now: float | None = None, stall_seconds: int | None = None
+    ) -> "BoardStats":
+        """Team-health signals the board uniquely surfaces (Phase 2, read-only).
+
+        Computed entirely from the existing rows + the append-only ``transitions``
+        audit — no new write-path instrumentation:
+
+        - **false_done** — items in ``done`` carrying NO passing :class:`Evidence`.
+          The done-gate makes this impossible through the normal path, so a non-empty
+          list is an integrity alarm (a hand-edited db / a bypassed gate).
+        - **redispatched** — items claimed (``planned→running``) more than once: work
+          that a stale-lease reclaim forced a second runner to redo (the materialised
+          duplicate-work signal — a purely concurrent claim that the atomic CAS averts
+          instantly leaves no trace by design, so it is not, and need not be, counted).
+        - **reclaimed_stale** — total ``recover_stale_running`` reclaims (dead-run
+          recovery events).
+        - **blocked_aged / human_required_aged** — items stuck in ``blocked`` / needing
+          a human, untouched longer than ``stall_seconds`` (a stalled team).
+        - **dropped_handoffs** — items whose handoff baton was set but that then sat
+          idle (not ``done``) past ``stall_seconds`` — a handoff nobody picked up.
+
+        ``now`` / ``stall_seconds`` default to the board's injected clock / configured
+        window (overridable for tests). Raises :class:`BoardError` on a db error.
+
+        The three reads run inside ONE deferred read transaction: as separate
+        autocommit statements they could straddle a concurrent ``board run``'s claim,
+        so the state counts came from a pre-claim world while the audit-derived
+        ``redispatched`` / ``reclaimed_stale`` came from a post-claim one — a reported
+        integrity alarm describing a state that never existed."""
+        t = self._now() if now is None else now
+        window = self._stall_seconds if stall_seconds is None else max(1, stall_seconds)
+        cutoff = t - window
+        try:
+            self._conn.execute("BEGIN")  # deferred: a consistent read snapshot
+            items = [
+                _row_to_item(r)
+                for r in self._conn.execute("SELECT * FROM work_items").fetchall()
+            ]
+            redispatched = [
+                r["item_id"]
+                # A re-dispatch is a CLAIM: every claim (claim/next_runnable) records a
+                # planned→running transition, so >1 of those means the item was claimed,
+                # reclaimed, and claimed again (work redone). Match `from_state` too: a
+                # same-state running→running annotation (a `board update` on a running
+                # item) ALSO has to_state='running' but is NOT a re-dispatch, so a bare
+                # to_state filter would over-count it (codex-found major).
+                # Live rows UNION the compacted rollups (#118): `board compact`
+                # folds trimmed claim rows into transition_rollups, so the count
+                # is live + rolled-up, identical before and after a compaction.
+                for r in self._conn.execute(
+                    "SELECT item_id FROM ("
+                    "  SELECT item_id, COUNT(*) AS c FROM transitions"
+                    "  WHERE from_state=? AND to_state=? GROUP BY item_id"
+                    "  UNION ALL"
+                    "  SELECT item_id, claim_count FROM transition_rollups"
+                    ") GROUP BY item_id HAVING SUM(c) > 1",
+                    (WorkState.PLANNED.value, WorkState.RUNNING.value),
+                ).fetchall()
+            ]
+            reclaimed_stale = self._conn.execute(
+                "SELECT (SELECT COUNT(*) FROM transitions WHERE to_state=? AND note=?)"
+                " + COALESCE((SELECT value FROM transition_counters"
+                "             WHERE name='reclaimed_stale'), 0) AS c",
+                (WorkState.PLANNED.value, _STALE_RECLAIM_NOTE),
+            ).fetchone()["c"]
+            self._conn.execute("COMMIT")
+        except Exception as exc:
+            # Broad, like every other transactional method: a non-sqlite error (a
+            # corrupt row's ValueError from _row_to_item) must still release the
+            # open read transaction rather than leaking it onto this connection.
+            self._safe_rollback()
+            raise BoardError(f"stats failed: {exc}") from exc
+
+        by_state: dict[str, int] = {}
+        false_done: list[str] = []
+        blocked_aged: list[str] = []
+        human_required_aged: list[str] = []
+        dropped_handoffs: list[str] = []
+        for it in items:
+            by_state[it.state.value] = by_state.get(it.state.value, 0) + 1
+            aged = it.updated_at <= cutoff
+            if it.state == WorkState.DONE and not _has_verification(it.evidence):
+                false_done.append(it.id)
+            if it.state == WorkState.BLOCKED and aged:
+                blocked_aged.append(it.id)
+            if it.human_required and it.state != WorkState.DONE and aged:
+                human_required_aged.append(it.id)
+            if it.handoff and it.state != WorkState.DONE and aged:
+                dropped_handoffs.append(it.id)
+        return BoardStats(
+            total=len(items),
+            by_state=by_state,
+            false_done=false_done,
+            redispatched=redispatched,
+            reclaimed_stale=int(reclaimed_stale),
+            blocked_aged=blocked_aged,
+            human_required_aged=human_required_aged,
+            dropped_handoffs=dropped_handoffs,
+            stall_seconds=window,
+        )
+
+    def compact_transitions(
+        self, *, older_than_seconds: float, now: float | None = None
+    ) -> int:
+        """Aggregate-then-trim the append-only ``transitions`` audit (#118).
+
+        Manual-only (``board compact`` — the same explicit/human deletion rule
+        as retained workspaces; nothing auto-triggers this). One
+        ``BEGIN IMMEDIATE`` transaction: rows older than the cutoff have their
+        stats-bearing aggregates folded first — per-item ``planned→running``
+        claim counts into ``transition_rollups`` and stale-reclaim rows into
+        the ``reclaimed_stale`` counter, which :meth:`stats` reads additively,
+        so its numbers are identical before and after — and are then deleted.
+        Rows newer than the cutoff always survive (recent per-item history for
+        ``board show``). The scratch-ledger backfill runs FIRST, inside the
+        same transaction: it scans historical claim rows, and trimming them
+        beforehand would silently disable it on an old board. Returns the
+        number of rows removed; raises :class:`BoardError` on any failure
+        (rolled back — the broad-rollback rule).
+        """
+        # A DESTRUCTIVE threshold is never clamped: a negative (or NaN) window
+        # silently became 0 — "trim everything up to now", i.e. the whole audit
+        # — which is exactly the nonpositive case runs.keep_last rejects. 0 is
+        # still legal and means the explicit "trim all existing history".
+        # `< 0` is NOT sufficient: an underflowing negative literal (-1e-999)
+        # becomes signed NEGATIVE ZERO, for which `-0.0 < 0` is False — it
+        # would slip through and trim as 0, i.e. the whole audit, from an input
+        # the caller wrote as negative. Test the SIGN BIT instead.
+        if (
+            not math.isfinite(older_than_seconds)
+            or math.copysign(1.0, older_than_seconds) < 0
+        ):
+            raise BoardError(
+                f"older_than_seconds must be a finite value >= 0, got "
+                f"{older_than_seconds!r}"
+            )
+        t = self._now() if now is None else now
+        # A non-finite clock makes every finite row "old" — the same total-purge
+        # bypass by another route (an injected/broken clock rather than a flag).
+        if not math.isfinite(t):
+            raise BoardError(f"clock must return a finite value, got {t!r}")
+        cutoff = t - older_than_seconds
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            _backfill_run_ledger(self._conn)
+            for row in self._conn.execute(
+                "SELECT item_id, COUNT(*) AS c FROM transitions"
+                " WHERE from_state=? AND to_state=? AND at < ?"
+                " GROUP BY item_id",
+                (WorkState.PLANNED.value, WorkState.RUNNING.value, cutoff),
+            ).fetchall():
+                self._conn.execute(
+                    "INSERT INTO transition_rollups (item_id, claim_count)"
+                    " VALUES (?, ?)"
+                    " ON CONFLICT(item_id) DO UPDATE SET"
+                    " claim_count = claim_count + excluded.claim_count",
+                    (row["item_id"], row["c"]),
+                )
+            reclaims = self._conn.execute(
+                "SELECT COUNT(*) AS c FROM transitions"
+                " WHERE to_state=? AND note=? AND at < ?",
+                (WorkState.PLANNED.value, _STALE_RECLAIM_NOTE, cutoff),
+            ).fetchone()["c"]
+            if reclaims:
+                self._conn.execute(
+                    "INSERT INTO transition_counters (name, value)"
+                    " VALUES ('reclaimed_stale', ?)"
+                    " ON CONFLICT(name) DO UPDATE SET"
+                    " value = value + excluded.value",
+                    (reclaims,),
+                )
+            trimmed = self._conn.execute(
+                "DELETE FROM transitions WHERE at < ?", (cutoff,)
+            ).rowcount
+            self._conn.execute("COMMIT")
+            return int(trimmed)
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(f"compact failed: {exc}") from exc
+
+    def close(self) -> None:
+        """Close the connection (best-effort; idempotent)."""
+        try:
+            self._conn.close()
+        except sqlite3.Error:
+            pass
+
+    # ── internals ────────────────────────────────────────────────────────────
+
+    def _claim_where(self, where: str, where_params: tuple, run_id: str) -> WorkItem | None:
+        try:
+            self._conn.execute("BEGIN IMMEDIATE")
+            row = self._conn.execute(
+                f"SELECT * FROM work_items WHERE {where}", where_params
+            ).fetchone()
+            if row is None:
+                self._conn.execute("COMMIT")
+                return None
+            item = self._stamp_running(row, run_id)
+            self._conn.execute("COMMIT")
+            return item
+        except Exception as exc:
+            self._safe_rollback()
+            raise BoardError(f"claim failed: {exc}") from exc
+
+    def _stamp_running(self, row: sqlite3.Row, run_id: str) -> WorkItem:
+        """Inside an open transaction: move ``row`` (a planned item) → running,
+        stamping the lease. Returns the freshly-read item."""
+        now = self._now()
+        self._conn.execute(
+            "UPDATE work_items SET state=?, lease_run_id=?, claimed_at=?, updated_at=? "
+            "WHERE id=? AND state=?",
+            (WorkState.RUNNING.value, run_id, now, now, row["id"], WorkState.PLANNED.value),
+        )
+        self._insert_transition(
+            row["id"], WorkState.PLANNED.value, WorkState.RUNNING.value,
+            run_id, "claimed", now,
+        )
+        # P2 scratch ownership is load-bearing claim metadata: a failure rolls back
+        # the lease and audit with the surrounding claim transaction. One run_id owns
+        # at most one item's scratch namespace (it IS `board-run:{run_id}`), so a
+        # reused id is rejected — but say WHY. Left to the bare INSERT it surfaced as
+        # "claim failed: UNIQUE constraint failed: board_run_namespaces.run_id",
+        # which reads like board corruption rather than a caller reusing a run id.
+        clash = self._conn.execute(
+            "SELECT item_id FROM board_run_namespaces WHERE run_id=?", (run_id,)
+        ).fetchone()
+        if clash is not None:
+            raise BoardError(
+                f"run id {run_id!r} already owns the scratch namespace for item "
+                f"{clash['item_id']} — one run id claims at most one item"
+            )
+        self._conn.execute(
+            "INSERT INTO board_run_namespaces "
+            "(run_id, item_id, claimed_at, purged_at) VALUES (?,?,?,NULL)",
+            (run_id, row["id"], now),
+        )
+        return _row_to_item(
+            self._conn.execute("SELECT * FROM work_items WHERE id=?", (row["id"],)).fetchone()
+        )
+
+    def _deps_satisfied(self, deps: list[str], done_ids: set[str]) -> bool:
+        """True iff every dependency is in the preloaded ``done`` id set (a missing
+        dependency is conservatively unsatisfied — don't dispatch work whose
+        declared prerequisite isn't there). Called inside the ``next_runnable``
+        transaction; ``done_ids`` is read in that same transaction, so membership
+        is exactly what per-dependency SELECTs would have seen."""
+        return all(dep_id in done_ids for dep_id in deps)
+
+    def _insert_transition(
+        self, item_id: str, from_state: str | None, to_state: str, actor: str,
+        note: str, at: float,
+    ) -> None:
+        self._conn.execute(
+            "INSERT INTO transitions (item_id, from_state, to_state, actor, note, at) "
+            "VALUES (?,?,?,?,?,?)",
+            (item_id, from_state, to_state, actor, note, at),
+        )
+
+    def _safe_rollback(self) -> None:
+        try:
+            self._conn.execute("ROLLBACK")
+        except sqlite3.Error:
+            pass  # no active transaction (e.g. BEGIN itself failed) — nothing to undo
+
+
+# ── row <-> dataclass mapping ────────────────────────────────────────────────
+
+
+def _item_to_row(item: WorkItem) -> tuple:
+    return (
+        item.id, item.goal, item.task, item.state.value, item.owner_agent,
+        json.dumps(item.inputs), json.dumps(item.outputs), _dump_evidence(item.evidence),
+        item.handoff, int(item.human_required), item.blocked_reason,
+        json.dumps(item.depends_on), item.lease_run_id, item.claimed_at,
+        item.created_at, item.updated_at,
+    )
+
+
+def _row_to_item(row: sqlite3.Row) -> WorkItem:
+    return WorkItem(
+        id=row["id"],
+        goal=row["goal"],
+        task=row["task"],
+        state=WorkState(row["state"]),
+        owner_agent=row["owner_agent"],
+        inputs=_load_list(row["inputs"]),
+        outputs=_load_list(row["outputs"]),
+        evidence=_load_evidence(row["evidence"]),
+        handoff=row["handoff"],
+        human_required=bool(row["human_required"]),
+        blocked_reason=row["blocked_reason"],
+        depends_on=_load_list(row["depends_on"]),
+        lease_run_id=row["lease_run_id"],
+        claimed_at=row["claimed_at"],
+        created_at=row["created_at"],
+        updated_at=row["updated_at"],
+    )
+
+
+def _is_valid_item_id(item_id: object) -> bool:
+    """True iff ``item_id`` parses as a uuid (the shape every real id has). Lets
+    :meth:`Board.get` reject a malformed/guessed id as not-found before querying."""
+    try:
+        uuid.UUID(str(item_id))
+        return True
+    except (ValueError, TypeError, AttributeError):
+        return False
+
+
+def _row_to_decision(row: sqlite3.Row) -> Decision:
+    return Decision(
+        id=row["id"],
+        text=row["text"],
+        scope=row["scope"],
+        created_at=row["created_at"],
+        superseded_by=row["superseded_by"],
+        superseded_at=row["superseded_at"],
+    )
+
+
+def _load_list(raw: str) -> list[str]:
+    try:
+        v = json.loads(raw)
+    except (ValueError, TypeError):
+        return []
+    return [str(x) for x in v] if isinstance(v, list) else []
+
+
+def _dump_evidence(evidence: list[Evidence]) -> str:
+    return json.dumps([asdict(e) for e in evidence])
+
+
+def _load_evidence(raw: str) -> list[Evidence]:
+    try:
+        rows = json.loads(raw)
+    except (ValueError, TypeError):
+        return []
+    out: list[Evidence] = []
+    if not isinstance(rows, list):
+        return out
+    for d in rows:
+        if not isinstance(d, dict):
+            continue
+        try:
+            out.append(Evidence(
+                kind=str(d["kind"]), ref=str(d["ref"]), passed=bool(d["passed"]),
+                at=float(d["at"]), by=str(d.get("by", "")),
+            ))
+        except (KeyError, TypeError, ValueError):
+            continue  # skip a malformed evidence row, keep the rest
+    return out
+
+
+def _merge_unique(existing: list[str], new: list) -> list[str]:
+    """``existing`` then any ``new`` not already present — order-preserving dedup."""
+    out = list(existing)
+    seen = set(out)
+    for x in new:
+        s = str(x)
+        if s and s not in seen:
+            seen.add(s)
+            out.append(s)
+    return out
+
+
+def _same_review_provenance(existing: WorkItem, expected: WorkItem) -> bool:
+    """Whether an existing deterministic id still names the same source finding."""
+    source_evidence = expected.evidence[0]
+    return (
+        existing.task == expected.task
+        and existing.inputs == expected.inputs
+        and any(
+            evidence.kind == source_evidence.kind
+            and evidence.ref == source_evidence.ref
+            and evidence.passed is False
+            and evidence.by == source_evidence.by
+            for evidence in existing.evidence
+        )
+    )
+
+
+def _has_verification(evidence: list[Evidence]) -> bool:
+    """The ``done`` gate predicate: at least one PASSING evidence row.
+
+    A human sign-off is just an ``Evidence{kind:"human", passed=True}``, so it's
+    covered by ``passed`` — and a RECORDED human REJECTION (``kind=="human",
+    passed=False``) deliberately does NOT satisfy the gate (the ``passed`` field is
+    the verdict; the gate must honor it, not any human row regardless of outcome)."""
+    return any(e.passed for e in evidence)
+
+
+def _resolve_completed_state(
+    requested: object, evidence: list[Evidence]
+) -> tuple[WorkState, str]:
+    """Map a COMPLETED run + the agent's advisory ``state`` request → (state, note).
+
+    A completed run defaults to ``review`` ("finished, awaiting verification"). The
+    agent's request is advisory: ``done`` is honored only when the work is
+    independently verified (passing evidence / a human sign-off — i.e. a passing
+    quality gate), else it CLAMPS to ``review``; ``blocked`` is honored; anything
+    else (``None``/unknown/``review``/``running``/``planned``) → ``review``."""
+    req = requested if isinstance(requested, str) else None
+    if req == WorkState.DONE.value:
+        if _has_verification(evidence):
+            return WorkState.DONE, "agent completed; verified"
+        return WorkState.REVIEW, "agent requested done without verification — clamped to review"
+    if req == WorkState.BLOCKED.value:
+        return WorkState.BLOCKED, "agent reported blocked"
+    return WorkState.REVIEW, "agent completed; awaiting review"
+
+
+# ── prompt rendering + agent-output parsing (pure) ───────────────────────────
+
+#: The fenced-block language tag agents use to (optionally) report a board update.
+BOARD_FENCE = "syncmill-board"
+
+_UPDATE_INSTRUCTIONS = (
+    "When you finish, you MAY append ONE fenced block reporting the board update "
+    "(every field optional):\n"
+    "```" + BOARD_FENCE + "\n"
+    '{"state": "review", "handoff": "<note for whoever picks this up next>", '
+    '"outputs": ["<artifact or file you produced>"], "human_required": false}\n'
+    "```\n"
+    'Use "state": "blocked" with a "blocked_reason" if you cannot proceed, or '
+    '"human_required": true if a human must step in. Requesting "done" only takes '
+    "effect if the work is independently verified (a passing quality gate or a "
+    'human sign-off); otherwise it is recorded as "review".'
+)
+
+
+def render_item_prompt(item: WorkItem, active_decisions: list[str] | None = None) -> str:
+    """Build the deterministic prompt for a board item.
+
+    Reuses the ``_enrich_prompt`` shape (sectioned context, the task labeled
+    "Task:") plus the update-block convention. Decisions + the handoff baton are
+    injected DETERMINISTICALLY here (guaranteed in the prompt), never via ``shared``
+    top-k recall. ``active_decisions`` is the Phase-2 seam (v1 passes ``None``)."""
+    parts: list[str] = []
+    header = "You are working on a tracked work-board item."
+    if item.goal:
+        header += f"\nGoal: {item.goal}"
+    parts.append(header)
+    if active_decisions:
+        parts.append(
+            "Team decisions you MUST respect (do not re-litigate):\n"
+            + "\n".join(f"- {d}" for d in active_decisions)
+        )
+    if item.inputs:
+        parts.append("Inputs / prior artifacts:\n" + "\n".join(f"- {x}" for x in item.inputs))
+    if item.handoff:
+        parts.append(f"Handoff note from prior work on this item:\n{item.handoff}")
+    parts.append(f"Task: {item.task}")
+    parts.append(_UPDATE_INSTRUCTIONS)
+    return "\n\n".join(parts)
+
+
+def parse_board_update(raw: str) -> dict:
+    """Extract the optional ``syncmill-board`` fenced JSON object from ``raw``.
+
+    Its OWN parser (not a reuse of ``_extract_json_list``) applying the same
+    robustness philosophy as ``DecomposeStrategy._parse_subtasks``: strict,
+    degrade-to-``{}``, NEVER raises. No block, no closing fence, non-JSON, or a
+    non-object → ``{}``. A recognised object is sanitized field-by-field
+    (:func:`_sanitize_update`) — an unknown or malformed field is dropped, not
+    fatal, so one bad field can't discard a valid ``state``."""
+    if not raw:
+        return {}
+    block = _extract_board_block(raw)
+    if block is None:
+        return {}
+    try:
+        parsed = json.loads(block)
+    except (ValueError, TypeError, RecursionError):
+        # RecursionError (deeply-nested untrusted JSON) is a RuntimeError, not a
+        # ValueError — catch it too so the "NEVER raises" contract holds and a
+        # pathological board block degrades to {} like any other malformed input.
+        return {}
+    if not isinstance(parsed, dict):
+        return {}
+    return _sanitize_update(parsed)
+
+
+def _extract_board_block(raw: str) -> str | None:
+    """The text between a ``` + BOARD_FENCE opening fence and the next ``` fence, or
+    ``None`` if there is no such complete block. Deliberately requires the exact
+    ``BOARD_FENCE`` tag (not a bare ```` ``` ````), so an unrelated code block in
+    the agent's prose is never mistaken for a board update."""
+    lines = raw.splitlines()
+    start = None
+    for i, line in enumerate(lines):
+        s = line.strip()
+        if s.startswith("```") and s[3:].strip() == BOARD_FENCE:
+            start = i + 1
+            break
+    if start is None:
+        return None
+    body: list[str] = []
+    for line in lines[start:]:
+        s = line.strip()
+        # A genuine close fence — NOT a second board OPEN fence. This mirrors
+        # strip_board_block's guard, so the parser and the stripper agree on block
+        # bounds; without it a 2nd ```syncmill-board would be mis-read as block 1's
+        # close (and the two paths would disagree on what was a board update).
+        if s.startswith("```") and s[3:].strip() != BOARD_FENCE:
+            return "\n".join(body)
+        body.append(line)
+    return None  # no closing fence → malformed → degrade
+
+
+def _sanitize_update(parsed: dict) -> dict:
+    """Keep only the recognised update fields with correct types; drop the rest.
+
+    ``state``/``handoff``/``blocked_reason``: strings. ``human_required``: bool.
+    ``outputs``: a list of non-empty strings, ALL-OR-NOTHING (a mixed/partial list
+    is dropped, never salvaged to a subset — the ``_parse_subtasks`` lesson). The
+    requested ``state`` is NOT validated here (``apply_update`` treats an unknown
+    request as "no request" → review), keeping this a pure shape filter."""
+    out: dict = {}
+    for key in ("state", "handoff", "blocked_reason"):
+        v = parsed.get(key)
+        if isinstance(v, str):
+            out[key] = v
+    if isinstance(parsed.get("human_required"), bool):
+        out["human_required"] = parsed["human_required"]
+    outputs = parsed.get("outputs")
+    if isinstance(outputs, list) and outputs and all(
+        isinstance(s, str) and s.strip() for s in outputs
+    ):
+        out["outputs"] = [s.strip() for s in outputs]
+    return out
+
+
+def strip_board_block(output: str) -> str:
+    """Return ``output`` with the ``syncmill-board`` fenced block removed.
+
+    Used to build the sanitized ``shared`` summary — the board-internal update
+    instructions/state must not leak into global memtomem knowledge. Mirrors
+    :func:`_extract_board_block`'s framing (the same exact-tag open fence + the next
+    ``` close); a block with no closing fence drops to end-of-output (consistent
+    with parse degrading it)."""
+    if not output:
+        return output
+    lines = output.splitlines()
+    out: list[str] = []
+    i, n = 0, len(lines)
+    while i < n:
+        s = lines[i].strip()
+        if s.startswith("```") and s[3:].strip() == BOARD_FENCE:
+            i += 1
+            while i < n and not lines[i].strip().startswith("```"):
+                i += 1
+            # Consume the stop line as this block's CLOSING fence only if it isn't
+            # itself a NEW board open fence — otherwise leave it for the outer loop
+            # to strip as its own block. Without this, two adjacent board blocks
+            # would mis-consume the second's OPEN fence as the first's close and
+            # leak the second block's JSON into the sanitized share.
+            if i < n:
+                cs = lines[i].strip()
+                if not (cs.startswith("```") and cs[3:].strip() == BOARD_FENCE):
+                    i += 1  # ordinary closing fence — drop it too
+            continue
+        out.append(lines[i])
+        i += 1
+    return "\n".join(out).strip()
+
+
+# ── human-facing rendering (CLI) ─────────────────────────────────────────────
+
+
+def _short(item_id: str) -> str:
+    return item_id[:8]
+
+
+def render_board(items: list[WorkItem]) -> str:
+    """One line per item for ``board list`` — id, state, goal, an abbreviated task.
+
+    The id is shown through ``printable_name`` too: listing reads stored rows
+    without the uuid check ``Board.get`` applies, so an LF in one would forge a
+    row."""
+    if not items:
+        return "[syncmill] board is empty"
+    lines = []
+    for it in items:
+        flags = []
+        if it.human_required:
+            flags.append("human-required")
+        if it.depends_on:
+            flags.append(f"deps={len(it.depends_on)}")
+        flag = f"  ({', '.join(flags)})" if flags else ""
+        goal = f"[{_p(it.goal)}] " if it.goal else ""
+        task = _p(it.task)
+        task = task if len(task) <= 60 else task[:57] + "..."
+        lines.append(f"  {_p(it.id)}  {it.state.value:<8}  {goal}{task}{flag}")
+    return "\n".join(lines)
+
+
+def render_item(item: WorkItem, transitions: list[dict] | None = None) -> str:
+    """A detailed multi-line view for ``board show`` / ``board add`` confirmation.
+
+    Every free-text field is one display line through ``printable_name``: tasks,
+    handoffs and outputs come from agents and imports, and an embedded control
+    or newline must neither drive the terminal nor forge a field line."""
+    lines = [
+        f"id:       {_p(item.id)}",
+        f"state:    {item.state.value}",
+        f"goal:     {_p(item.goal) if item.goal else '-'}",
+        f"task:     {_p(item.task)}",
+        f"owner:    {_p(item.owner_agent) if item.owner_agent else '-'}",
+    ]
+    if item.depends_on:
+        lines.append(f"depends:  {', '.join(_p(d) for d in item.depends_on)}")
+    if item.inputs:
+        lines.append(f"inputs:   {', '.join(_p(i) for i in item.inputs)}")
+    if item.outputs:
+        lines.append(f"outputs:  {', '.join(_p(o) for o in item.outputs)}")
+    if item.handoff:
+        lines.append(f"handoff:  {_p(item.handoff)}")
+    if item.human_required:
+        lines.append("human:    REQUIRED")
+    if item.blocked_reason:
+        lines.append(f"blocked:  {_p(item.blocked_reason)}")
+    if item.evidence:
+        lines.append("evidence:")
+        for e in item.evidence:
+            mark = "pass" if e.passed else "fail"
+            by = f" (by {_p(e.by)})" if e.by else ""
+            lines.append(f"  - [{_p(e.kind)}/{mark}] {_p(e.ref)}{by}")
+    if transitions:
+        lines.append("history:")
+        for t in transitions:
+            # Raw audit rows, unlike the item's own WorkState.
+            frm = _p(str(t["from_state"])) if t.get("from_state") else "·"
+            to = _p(str(t["to_state"]))
+            note = f" — {_p(str(t['note']))}" if t.get("note") else ""
+            actor = _p(str(t.get("actor") or "?"))
+            lines.append(f"  {frm} → {to}  [{actor}]{note}")
+    return "\n".join(lines)
+
+
+def render_decision(decision: Decision) -> str:
+    """A one-line ``board decide`` confirmation: id, scope, and the decision text,
+    each through ``printable_name`` so none can start a line of its own."""
+    scope = f"[{_p(decision.scope)}] " if decision.scope else "[global] "
+    return f"  {_p(decision.id)}  {scope}{_p(decision.text)}"
+
+
+def render_decisions(decisions: list[Decision]) -> str:
+    """The active-decisions view for ``board decisions`` (one line per decision)."""
+    if not decisions:
+        return "[syncmill] no active decisions"
+    return "\n".join(render_decision(d) for d in decisions)
+
+
+def render_board_stats(stats: BoardStats) -> str:
+    """A human-readable ``board stats`` report (also reused by the gateway tool).
+
+    Counts are always shown; the offending item ids are appended only when non-empty
+    so a healthy board stays terse. The ids come from raw work-item,
+    transition and rollup rows and are shown through ``printable_name``."""
+    lines = [f"items: {stats.total}"]
+    if stats.by_state:
+        breakdown = "  ".join(
+            f"{state}={stats.by_state[state]}" for state in sorted(stats.by_state)
+        )
+        lines.append(f"  by state:  {breakdown}")
+    lines.append(f"  reclaimed (stale-lease):  {stats.reclaimed_stale}")
+
+    def _signal(label: str, ids: list[str]) -> None:
+        shown = ", ".join(_p(str(i)) for i in ids)
+        lines.append(f"  {label}:  {len(ids)}" + (f"  ({shown})" if ids else ""))
+
+    _signal("redispatched (work redone)", stats.redispatched)
+    _signal("false-done (done, unverified)", stats.false_done)
+    _signal(f"blocked > {stats.stall_seconds}s", stats.blocked_aged)
+    _signal(f"human-required > {stats.stall_seconds}s", stats.human_required_aged)
+    _signal(f"dropped handoffs > {stats.stall_seconds}s", stats.dropped_handoffs)
+    return "\n".join(lines)
+
+
+def build_board(config: BoardConfig) -> Board | None:
+    """The board described by ``config``, or ``None`` when disabled
+    (``enabled=False``, the default) — so the disabled path never opens a file and
+    plain ``syncmill run`` is unchanged. Mirrors ``build_breaker``/``build_gate``,
+    except the board is LOAD-BEARING (a corrupt db raises :class:`BoardError`, it
+    does not degrade)."""
+    if not config.enabled:
+        return None
+    return Board(
+        config.db_path,
+        lease_timeout_seconds=config.lease_timeout_seconds,
+        stall_seconds=config.stall_seconds,
+    )