fix(backlog): claim locks one ready row (LIMIT 1) to prevent claimer starvation

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

docs/fleet/NORTH_STAR.md

@@ -0,0 +1,70 @@
+# Mosaic Fleet — NORTH STAR
+
+> **Generated file — do not edit by hand.**
+> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure
+> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).
+> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.
+
+## Mission
+
+A self-driving Mosaic delivery fleet that 24/7 unattended converts a machine-readable goal set into merged, CI-green, budget-bounded change — looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN native backlog/dispatch engine.
+
+## Substrate
+
+The Mosaic Backlog is the backlog of record + dispatch engine, built on Mosaic's native Postgres storage service (@mosaicstack/db drizzle; PGlite-embedded by default, full Postgres by config). NOT Hermes.
+
+## Standing objectives
+
+- **NS-1** — Single machine-readable source (this file) drives planning; prose docs are projections.
+- **NS-2** — Every backlog item is an independently-shippable unit with stable id, priority, depends_on DAG, represented as a Mosaic Backlog card; spend tracked as advisory projection.
+- **NS-3** — The supervisor guarantees movement: no idle agent while ready dependency-satisfied work exists; no empty backlog without a replan request; assignment via Mosaic native dispatch/claim.
+- **NS-4** — Exactly one merge-gate approver; nothing reaches main except via pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the backstop.
+- **NS-5** — Every unit bounded by wall-clock TTL on its claim; token caps enforced only where a real meter exists, else advisory.
+- **NS-6** — Context cleared between tasks for ephemeral runners (reset_between_tasks); persona+mission re-injected per task.
+- **NS-7** — Meta-loop (session-review + enhancer) continuously proposes small fleet-improvement PRs.
+- **NS-8** — Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored before every dispatch and every merge.
+
+## Success criteria
+
+- **AC-NS-1** — The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer) healthy across reboot.
+- **AC-NS-2** — A goal added to this YAML is decomposed to cards and either merged or escalated, with no human in the loop.
+- **AC-NS-3** — No PR merges with failure/error/no-status/timeout CI, and none bypass pr-merge.sh.
+- **AC-NS-4** — TTL is enforced on claims; token caps remain advisory until a real meter exists.
+- **AC-NS-5** — Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+
+## Workstreams
+
+| id  | title                                                            |
+| --- | ---------------------------------------------------------------- |
+| A   | Substrate — Mosaic Backlog on native Postgres storage service    |
+| B   | Supervisor — movement guarantee, two-agent floor, dispatch/claim |
+| C   | Planner — goal decomposition into independently-shippable cards  |
+| D   | Merge-gate — single approver, pr-merge.sh after CI wait          |
+| E   | Meta-loop — session-review + enhancer improvement PRs            |
+| F   | Safety-rails — TTL claims, advisory spend, PAUSE kill-switch     |
+
+## Goals (backlog projection)
+
+| id  | title                                                                  | phase | priority    | depends_on |
+| --- | ---------------------------------------------------------------------- | ----- | ----------- | ---------- |
+| A1  | Machine-readable NORTH_STAR.yaml + Markdown projection                 | 1     | must-have   | —          |
+| A2  | Mosaic Backlog schema + storage-service card store (drizzle/PGlite)    | 1     | must-have   | A1         |
+| A3a | Card lifecycle — create/claim/release with stable ids + depends_on DAG | 1     | must-have   | A2         |
+| A3b | TTL-bounded claim enforcement (wall-clock) on cards                    | 1     | must-have   | A3a        |
+| A4  | Advisory spend projection per card (degrades to TTL, no real meter)    | 1     | should-have | A3a        |
+| B1  | Supervisor tick — readiness scan, two-agent-floor health check         | 2     | must-have   | A3a        |
+| B2  | Native dispatch/claim — assign ready dependency-satisfied work         | 2     | must-have   | A3b, B1    |
+| B3a | Planner decompose — goal added to YAML → cards                         | 2     | must-have   | A2, B1     |
+| B3b | Replan request on empty backlog; escalate on no-decompose              | 2     | should-have | B3a        |
+| G1  | PAUSE kill-switch + merge-gate honored before dispatch and merge       | 2     | must-have   | B2         |
+
+## Assumptions (vetoable)
+
+- **ASM-1** (vetoable) — The Mosaic Backlog on the native Postgres storage service is the backlog of record.
+- **ASM-2** (vetoable) — Claude gate roles have no native busy status, so readiness = pane-idle + heartbeat.
+- **ASM-3** (vetoable) — Two-agent floor = 1 orchestrator + >=1 enhancer.
+
+## Spend
+
+- **advisory:** true
+- No per-task token meter yet; budgets degrade to TTL. Spend is tracked only as an advisory projection alongside each card.

docs/fleet/NORTH_STAR.yaml

@@ -0,0 +1,169 @@
+# Mosaic Fleet — NORTH_STAR (machine-readable source of truth)
+#
+# This file is the single machine-readable source of truth for fleet planning.
+# Prose docs (including NORTH_STAR.md) are deterministic PROJECTIONS of this file.
+# Regenerate the Markdown projection with the pure generator in
+# packages/mosaic/src/commands/fleet.ts (renderNorthStarMarkdown). Edit the YAML,
+# never the .md.
+#
+# Self-contained Mosaic. NO Hermes runtime dependency. The backlog of record is
+# the Mosaic Backlog on Mosaic's OWN native Postgres storage service.
+
+version: 1
+
+mission: >-
+  A self-driving Mosaic delivery fleet that 24/7 unattended converts a
+  machine-readable goal set into merged, CI-green, budget-bounded change —
+  looping plan→backlog→assign→execute→verify→merge→reassess — on Mosaic's OWN
+  native backlog/dispatch engine.
+
+substrate:
+  note: >-
+    The Mosaic Backlog is the backlog of record + dispatch engine, built on
+    Mosaic's native Postgres storage service (@mosaicstack/db drizzle;
+    PGlite-embedded by default, full Postgres by config). NOT Hermes.
+
+standing_objectives:
+  - id: NS-1
+    text: >-
+      Single machine-readable source (this file) drives planning; prose docs are
+      projections.
+  - id: NS-2
+    text: >-
+      Every backlog item is an independently-shippable unit with stable id,
+      priority, depends_on DAG, represented as a Mosaic Backlog card; spend
+      tracked as advisory projection.
+  - id: NS-3
+    text: >-
+      The supervisor guarantees movement: no idle agent while ready
+      dependency-satisfied work exists; no empty backlog without a replan
+      request; assignment via Mosaic native dispatch/claim.
+  - id: NS-4
+    text: >-
+      Exactly one merge-gate approver; nothing reaches main except via
+      pr-merge.sh after pr-ci-wait.sh success; Gitea branch protection is the
+      backstop.
+  - id: NS-5
+    text: >-
+      Every unit bounded by wall-clock TTL on its claim; token caps enforced
+      only where a real meter exists, else advisory.
+  - id: NS-6
+    text: >-
+      Context cleared between tasks for ephemeral runners
+      (reset_between_tasks); persona+mission re-injected per task.
+  - id: NS-7
+    text: >-
+      Meta-loop (session-review + enhancer) continuously proposes small
+      fleet-improvement PRs.
+  - id: NS-8
+    text: >-
+      Single operator-flippable PAUSE kill-switch (fleet/run/PAUSED) honored
+      before every dispatch and every merge.
+
+success_criteria:
+  - id: AC-NS-1
+    text: >-
+      The supervisor keeps a two-agent floor (1 orchestrator + >=1 enhancer)
+      healthy across reboot.
+  - id: AC-NS-2
+    text: >-
+      A goal added to this YAML is decomposed to cards and either merged or
+      escalated, with no human in the loop.
+  - id: AC-NS-3
+    text: >-
+      No PR merges with failure/error/no-status/timeout CI, and none bypass
+      pr-merge.sh.
+  - id: AC-NS-4
+    text: >-
+      TTL is enforced on claims; token caps remain advisory until a real meter
+      exists.
+  - id: AC-NS-5
+    text: >-
+      Flipping fleet/run/PAUSED halts dispatch and merges within one tick.
+
+workstreams:
+  - id: A
+    title: Substrate — Mosaic Backlog on native Postgres storage service
+  - id: B
+    title: Supervisor — movement guarantee, two-agent floor, dispatch/claim
+  - id: C
+    title: Planner — goal decomposition into independently-shippable cards
+  - id: D
+    title: Merge-gate — single approver, pr-merge.sh after CI wait
+  - id: E
+    title: Meta-loop — session-review + enhancer improvement PRs
+  - id: F
+    title: Safety-rails — TTL claims, advisory spend, PAUSE kill-switch
+
+goals:
+  - id: A1
+    title: Machine-readable NORTH_STAR.yaml + Markdown projection
+    phase: 1
+    priority: must-have
+    depends_on: []
+  - id: A2
+    title: Mosaic Backlog schema + storage-service card store (drizzle/PGlite)
+    phase: 1
+    priority: must-have
+    depends_on: [A1]
+  - id: A3a
+    title: Card lifecycle — create/claim/release with stable ids + depends_on DAG
+    phase: 1
+    priority: must-have
+    depends_on: [A2]
+  - id: A3b
+    title: TTL-bounded claim enforcement (wall-clock) on cards
+    phase: 1
+    priority: must-have
+    depends_on: [A3a]
+  - id: A4
+    title: Advisory spend projection per card (degrades to TTL, no real meter)
+    phase: 1
+    priority: should-have
+    depends_on: [A3a]
+  - id: B1
+    title: Supervisor tick — readiness scan, two-agent-floor health check
+    phase: 2
+    priority: must-have
+    depends_on: [A3a]
+  - id: B2
+    title: Native dispatch/claim — assign ready dependency-satisfied work
+    phase: 2
+    priority: must-have
+    depends_on: [A3b, B1]
+  - id: B3a
+    title: Planner decompose — goal added to YAML → cards
+    phase: 2
+    priority: must-have
+    depends_on: [A2, B1]
+  - id: B3b
+    title: Replan request on empty backlog; escalate on no-decompose
+    phase: 2
+    priority: should-have
+    depends_on: [B3a]
+  - id: G1
+    title: PAUSE kill-switch + merge-gate honored before dispatch and merge
+    phase: 2
+    priority: must-have
+    depends_on: [B2]
+
+assumptions:
+  - id: ASM-1
+    vetoable: true
+    text: >-
+      The Mosaic Backlog on the native Postgres storage service is the backlog
+      of record.
+  - id: ASM-2
+    vetoable: true
+    text: >-
+      Claude gate roles have no native busy status, so readiness = pane-idle +
+      heartbeat.
+  - id: ASM-3
+    vetoable: true
+    text: 'Two-agent floor = 1 orchestrator + >=1 enhancer.'
+
+spend:
+  advisory: true
+  note: >-
+    No per-task token meter yet; budgets degrade to TTL. Spend is tracked only
+    as an advisory projection alongside each card.

docs/fleet/backlog-conventions.md

@@ -0,0 +1,138 @@
+# Fleet Backlog Conventions
+
+The **backlog** is Mosaic's native backlog-of-record for fleet work. It is built
+end-to-end on Mosaic's own storage layer (`@mosaicstack/db`, drizzle/Postgres)
+and surfaced as `mosaic fleet backlog <sub> --json`.
+
+> **Mosaic-native, no Hermes.** This backlog REPLACES the former Hermes adapter.
+> There is **no** runtime dependency on Hermes, `hermes kanban`, or `~/.hermes`
+> anywhere in this feature. Anything previously delegated to Hermes is recreated
+> here on Mosaic's own Postgres storage layer.
+
+## Storage tier — PGlite by default, Postgres by config
+
+The backlog uses the existing Mosaic storage layer; there is **no** new database
+engine (no sqlite, no raw client).
+
+| Condition                      | Tier                 | Data location                    |
+| ------------------------------ | -------------------- | -------------------------------- |
+| `DATABASE_URL` set             | Full server Postgres | the configured database          |
+| `PGLITE_DATA_DIR` set (no URL) | Embedded PGlite      | that directory                   |
+| neither (default)              | Embedded PGlite      | `~/.config/mosaic/fleet/backlog` |
+
+PGlite is real Postgres semantics in-process — including the row locks the atomic
+claim relies on — so the **same code** runs on a laptop (embedded, single-host
+default) and on a full Postgres deployment. Switching tiers is config-only.
+
+The schema (`backlog` table) is created automatically on first CLI use:
+`runMigrations()` for Postgres, `runPgliteMigrations()` for embedded PGlite.
+
+### Update safety
+
+The embedded PGlite store lives under `~/.config/mosaic/fleet/backlog`, which is
+listed in `PRESERVE_PATHS` in `packages/mosaic/framework/install.sh`. This means
+`mosaic update` (which runs the framework sync with `rsync --delete`) will **not**
+wipe the operator's backlog — same protection as the roster, per-agent env, and
+heartbeat run dir.
+
+## Card schema
+
+A card is one row in the `backlog` table:
+
+| Column              | Type                | Notes                                                         |
+| ------------------- | ------------------- | ------------------------------------------------------------- |
+| `id`                | text (PK)           | Stable, caller-supplied id (e.g. `A4`, `fleet-001`).          |
+| `title`             | text                | Required.                                                     |
+| `body`              | text (nullable)     | Free-form description.                                        |
+| `phase`             | text (nullable)     | Board/phase grouping (see below).                             |
+| `priority`          | int (default 0)     | **Higher = sooner.** Claim picks the max-priority ready card. |
+| `status`            | enum                | `ready` \| `claimed` \| `blocked` \| `done`.                  |
+| `depends_on`        | jsonb `string[]`    | DAG edges — ids of cards this one depends on.                 |
+| `claim_owner`       | text (nullable)     | Owner token of the active claim.                              |
+| `claim_ttl_seconds` | int (nullable)      | TTL of the active claim.                                      |
+| `claimed_at`        | timestamptz (null)  | When the claim was taken. `claimed_at + ttl` = expiry.        |
+| `attempts`          | int (default 0)     | Incremented each time the card is claimed.                    |
+| `idempotency_key`   | text (unique, null) | Dedups `create`; NULLs are distinct in Postgres.              |
+| `acceptance`        | jsonb (nullable)    | Acceptance criteria (array of strings or object).             |
+| `created_at`        | timestamptz         |                                                               |
+| `updated_at`        | timestamptz         |                                                               |
+
+`depends_on` is modeled as a `jsonb` array column rather than a separate edge
+table. Justification: it matches the repo's existing style (e.g. `tasks.tags`,
+`agents.skills`, `routing_rules.conditions` are all jsonb arrays), keeps a card
+self-contained, and the DAG is small (per-card dependency lists), so a join table
+would add ceremony without benefit.
+
+### Board / phase convention
+
+`phase` is a free-form grouping string used as the board column / milestone label
+(e.g. `M1`, `fleet`, `infra`). `list --phase <phase>` filters to one board lane.
+`priority` orders cards **within** the ready pool regardless of phase.
+
+## Status lifecycle
+
+```
+            create
+              │
+              ▼
+   ┌──────► ready ───── claim ─────► claimed ───── complete ─────► done
+   │          │                         │
+   │       block                  reclaim (TTL expiry or --id)
+   │          ▼                         │
+   │       blocked                      └──────────────────────────┘ (back to ready)
+   └──────────┘  (reclaim / re-create can return a card to ready)
+```
+
+- **ready** — eligible to be claimed once every `depends_on` card is `done`.
+- **claimed** — a worker holds it; `claim_owner` + `claimed_at` set.
+- **blocked** — explicitly parked; never auto-claimed.
+- **done** — completed; satisfies dependents.
+
+## Atomic claim (`FOR UPDATE SKIP LOCKED`) + TTL
+
+`claim` is atomic. Inside a single transaction it locks candidate `ready` rows
+with `SELECT ... FOR UPDATE SKIP LOCKED` (via the drizzle `sql` operator), picks
+the highest-priority deps-satisfied card, and flips it to `claimed`. Because a row
+already locked by a concurrent claimer is **skipped**, two claimers can **never**
+both win the same card — the loser falls through to the next candidate or gets
+`null`. (Proven by the concurrency tests in `packages/db/src/backlog.spec.ts`.)
+
+- **Deps gate:** a card is only claimable when every id in `depends_on` is `done`.
+- **TTL:** `claim --ttl <sec>` (default **900s**) records `claim_ttl_seconds`.
+- **reclaim:** releases claims whose `claimed_at + ttl` is in the past (expired)
+  back to `ready`, clearing the claim fields. `reclaim --id <id>` force-releases a
+  specific card regardless of expiry. This is how a crashed worker's card returns
+  to the pool.
+
+## CLI — `mosaic fleet backlog <sub> --json`
+
+All subcommands support `--json`.
+
+| Subcommand                                                                                    | Purpose                                                                                   |
+| --------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `create --id --title [--body --phase --priority --depends-on --acceptance --idempotency-key]` | Create a card; `idempotency_key` dedups (repeat returns the existing card).               |
+| `list [--status --phase --ready-only]`                                                        | List cards. `--ready-only` = status `ready` AND all deps `done`.                          |
+| `claim --owner [--ttl <sec> --id <id>]`                                                       | Atomically claim the highest-priority ready card (or `--id`). Returns the card or `null`. |
+| `reclaim [--id <id>]`                                                                         | Release expired claims (or a specific card) back to `ready`.                              |
+| `link --from --to`                                                                            | Add a `depends_on` edge (`--from` depends on `--to`).                                     |
+| `stats`                                                                                       | Counts by status, oldest-ready age, expired-claim count.                                  |
+| `block --id`                                                                                  | Set a card to `blocked`.                                                                  |
+| `complete --id`                                                                               | Set a card to `done` (releases any claim).                                                |
+
+### Example
+
+```sh
+# Seed two cards, the second depends on the first.
+mosaic fleet backlog create --id A1 --title "schema" --priority 5
+mosaic fleet backlog create --id A2 --title "service" --depends-on A1 --priority 9
+
+# A2 is gated on A1, so claim returns A1 first.
+mosaic fleet backlog claim --owner worker-1 --ttl 600 --json
+
+# Finish A1; now A2 is ready.
+mosaic fleet backlog complete --id A1
+mosaic fleet backlog list --ready-only --json
+
+# Recover stalled work.
+mosaic fleet backlog reclaim --json
+```

docs/scratchpads/h1b-pane-idle-signal.md

@@ -0,0 +1,53 @@
+# H1b — tmux pane idle signal wiring
+
+## Objective
+
+Feed `classifyReadiness()` a real idle signal on tmux 3.4 by deriving `idleSeconds` from the first available tmux timestamp source: pane activity, then window activity, then session activity.
+
+## Scope
+
+- `packages/mosaic/src/commands/fleet.ts`
+  - Extend `buildTmuxListPanesCommand()` format to include `#{window_activity}` and `#{session_activity}` after the existing fields.
+  - Update `parseTmuxListPanes()` to choose the first non-empty finite positive timestamp and clamp future idle values to 0.
+- `packages/mosaic/src/commands/fleet.spec.ts`
+  - Cover pane/window/session activity parsing behavior, empty-field index alignment, null idle, future clamping, math correctness, and exact tmux format.
+
+## Out of Scope
+
+- No changes to `classifyReadiness()`, thresholds, `AgentPsRow`, or `fleet ps` rendering.
+- No merge by worker; orchestrator routes review/merge.
+- Workers do not modify `docs/TASKS.md`.
+
+## PRD Alignment
+
+Aligned with `docs/fleet/PRD.md` FR-1 and acceptance criteria for truthful `mosaic fleet ps` pane/pid/idle observability.
+
+## Plan
+
+1. Sync branch from latest `origin/main` and install dependencies with required pnpm env.
+2. Add/confirm reproducer tests for tmux 3.4 empty `pane_activity` and new fallback behavior.
+3. Implement the focused parser/format change only.
+4. Run required build, baseline gates, fleet vitest, and independent review.
+5. Run pre-push queue guard, push branch, and open PR to `main` with Mosaic wrapper.
+
+## Progress
+
+- 2026-06-24: Branch `fix/fleet-pane-idle-activity` created from `origin/main` @ `ec8dd7c` after fetching.
+- 2026-06-24: Session-start generated local `.mosaic/orchestrator/*` changes on the previous release branch; stashed as `coder1 session-start state before H1b` to keep this branch clean.
+- 2026-06-24: Added TDD coverage for the tmux 3.4 production case (`pane_activity` empty, `window_activity` populated), exact new list-panes format, null/future/multiple-source behavior.
+- 2026-06-24: Implemented parser fallback without changing readiness classifier thresholds or render shape.
+
+## Verification Evidence
+
+- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
+- Reproducer before implementation: `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — failed as expected (old format, no fallback, negative future idle).
+- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
+- `pnpm typecheck` — pass, 41/41 tasks successful.
+- `pnpm lint` — pass, 23/23 tasks successful.
+- `pnpm format:check` — pass, all matched files use Prettier style.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 176 tests.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
+
+## Risks / Blockers
+
+- No current blocker.

docs/scratchpads/h2-readiness-available.md

@@ -0,0 +1,70 @@
+# H2 — readiness semantics: available, not stuck
+
+## Objective
+
+Correct fleet readiness semantics so a healthy long-idle agent is reported as `available` (good/assignable) instead of `stuck` (fault). Reserve `stuck` in the type/JSON value space for future positive block evidence.
+
+## Scope
+
+- `packages/mosaic/src/commands/fleet.ts`
+  - replace `idle` readiness state with `available`
+  - keep `stuck` in the union but stop emitting it from idle-only heuristics
+  - remove stuck threshold helper/env handling
+  - remove IDLE/STUCK alarm flags from table rendering
+- `packages/mosaic/src/commands/fleet.spec.ts`
+  - update classifier branch/boundary tests
+  - assert very long idle maps to `available`, not `stuck`
+  - update table/JSON assertions for available with no alarm flags
+  - remove stuck threshold helper tests
+
+## Acceptance Criteria
+
+- `classifyReadiness()` remains pure/total/never-throw and maps:
+  - dead/stale/unknown unchanged
+  - busy/null/undefined/non-finite idle to `working`
+  - idle >= activity threshold to `available`
+  - idle < activity threshold to `working`
+- No idle-derived path emits `stuck`.
+- `MOSAIC_HEARTBEAT_IDLE_THRESHOLD` remains backward compatible as the working→available activity threshold.
+- `MOSAIC_HEARTBEAT_STUCK_THRESHOLD` and helper/default are removed.
+- `fleet ps` keeps the idle-seconds column header `IDLE`, renders `available` in HB label, and does not add IDLE/STUCK warning flags.
+- Local gates green: build precheck, typecheck, lint, format:check, fleet vitest.
+- PR opened against `main`; no merge by worker.
+
+## Constraints / Assumptions
+
+- Source branch: `origin/main` @ `1020cfa`.
+- `docs/TASKS.md` is orchestrator-owned; worker will not modify it.
+- Documentation impact is captured in this scratchpad and PR description; no user/admin guide behavior beyond CLI readiness label semantics.
+
+## Plan
+
+1. Install dependencies with requested PNPM environment.
+2. Inspect current H1/H1b readiness implementation and tests.
+3. Update classifier types/helpers/rendering.
+4. Update focused tests.
+5. Run build precheck + required gates.
+6. Run automated code review, remediate any findings.
+7. Queue guard, push, open PR.
+
+## Progress
+
+- 2026-06-24: Branch created from `origin/main` @ `1020cfa`.
+- 2026-06-24: Replaced idle-derived `idle`/`stuck` outputs with `available`; retained `stuck` in type union for future positive block evidence.
+- 2026-06-24: Removed stuck threshold env/helper plumbing and IDLE/STUCK alarm flags.
+- 2026-06-24: Updated classifier and table-render tests for available semantics.
+
+## Verification Evidence
+
+- `pnpm install --store-dir "$HOME/.pnpm-store"` — pass.
+- `npx turbo build --filter=@mosaicstack/mosaic^...` — pass, 12/12 tasks successful.
+- `pnpm typecheck` — pass, 41/41 tasks successful.
+- `pnpm lint` — pass, 23/23 tasks successful.
+- `pnpm format:check` — pass, all matched files use Prettier style.
+- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/fleet.spec.ts` — pass, 177 tests.
+- `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` — approve, 0 findings (reviewed supplied diff; sandbox file-inspection limitation noted by tool).
+
+## Risks / Blockers
+
+- No current blocker.
+- Review tool could not inspect repo files directly due sandbox wrapper limitation, but it reviewed the supplied diff and approved with no findings.

packages/db/drizzle/0011_bitter_gateway.sql

@@ -0,0 +1,22 @@
+CREATE TYPE "public"."backlog_status" AS ENUM('ready', 'claimed', 'blocked', 'done');--> statement-breakpoint
+CREATE TABLE "backlog" (
+	"id" text PRIMARY KEY NOT NULL,
+	"title" text NOT NULL,
+	"body" text,
+	"phase" text,
+	"priority" integer DEFAULT 0 NOT NULL,
+	"status" "backlog_status" DEFAULT 'ready' NOT NULL,
+	"depends_on" jsonb DEFAULT '[]'::jsonb NOT NULL,
+	"claim_owner" text,
+	"claim_ttl_seconds" integer,
+	"claimed_at" timestamp with time zone,
+	"attempts" integer DEFAULT 0 NOT NULL,
+	"idempotency_key" text,
+	"acceptance" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"updated_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "backlog_status_priority_idx" ON "backlog" USING btree ("status","priority");--> statement-breakpoint
+CREATE INDEX "backlog_status_claimed_at_idx" ON "backlog" USING btree ("status","claimed_at");--> statement-breakpoint
+CREATE UNIQUE INDEX "backlog_idempotency_key_idx" ON "backlog" USING btree ("idempotency_key");

packages/db/drizzle/meta/_journal.json

@@ -78,6 +78,13 @@
       "when": 1745366400000,
       "tag": "0010_federation_enrollment_tokens",
       "breakpoints": true
+    },
+    {
+      "idx": 11,
+      "version": "7",
+      "when": 1782310438919,
+      "tag": "0011_bitter_gateway",
+      "breakpoints": true
     }
   ]
-}
+}

packages/db/src/backlog.spec.ts

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { sql } from 'drizzle-orm';
+import { createPgliteDb } from './client-pglite.js';
+import { runPgliteMigrations } from './migrate.js';
+import type { DbHandle } from './client.js';
+import { BacklogService } from './backlog.js';
+import { backlog } from './schema.js';
+
+// Helper: backdate a claim's claimed_at by 1 hour so it is past any short TTL.
+function sqlBackdate(id: string) {
+  return sql`UPDATE ${backlog} SET claimed_at = now() - interval '1 hour' WHERE ${backlog.id} = ${id}`;
+}
+
+/**
+ * Real Postgres semantics, no external server: embedded in-memory PGlite.
+ * The migration path creates the `backlog` table (and every other table) so the
+ * service runs against the actual generated schema, including the row locks the
+ * atomic-claim path depends on.
+ */
+async function freshService(): Promise<{ handle: DbHandle; svc: BacklogService }> {
+  const handle = createPgliteDb('memory://');
+  await runPgliteMigrations(handle);
+  return { handle, svc: new BacklogService(handle.db) };
+}
+
+describe('BacklogService', () => {
+  let handle: DbHandle;
+  let svc: BacklogService;
+
+  beforeEach(async () => {
+    ({ handle, svc } = await freshService());
+  });
+
+  afterEach(async () => {
+    await handle.close();
+  });
+
+  it('create then list returns the card', async () => {
+    await svc.create({ id: 'c1', title: 'First card', phase: 'M1', priority: 5 });
+    const all = await svc.list();
+    expect(all).toHaveLength(1);
+    expect(all[0]).toMatchObject({ id: 'c1', title: 'First card', phase: 'M1', status: 'ready' });
+  });
+
+  it('idempotency_key dedups create', async () => {
+    const a = await svc.create({ id: 'c1', title: 'one', idempotencyKey: 'k-1' });
+    const b = await svc.create({ id: 'c2', title: 'two', idempotencyKey: 'k-1' });
+    expect(b.id).toBe(a.id);
+    const all = await svc.list();
+    expect(all).toHaveLength(1);
+  });
+
+  it('list filters by status and phase', async () => {
+    await svc.create({ id: 'c1', title: 'a', phase: 'M1' });
+    await svc.create({ id: 'c2', title: 'b', phase: 'M2' });
+    await svc.block('c2');
+    expect(await svc.list({ phase: 'M1' })).toHaveLength(1);
+    expect(await svc.list({ status: 'blocked' })).toHaveLength(1);
+    expect((await svc.list({ status: 'blocked' }))[0]!.id).toBe('c2');
+  });
+
+  describe('atomic claim', () => {
+    it('two concurrent claimers on one card => exactly one wins', async () => {
+      await svc.create({ id: 'only', title: 'the one', priority: 10 });
+
+      // Two independent claimers race for the single ready card on the same db.
+      // The atomic claim path (`FOR UPDATE SKIP LOCKED` inside a transaction)
+      // guarantees the loser's locked row is skipped, so it can never also flip
+      // the card to claimed — it gets the next candidate (none) and returns null.
+      const svcA = new BacklogService(handle.db);
+      const svcB = new BacklogService(handle.db);
+
+      const [a, b] = await Promise.all([
+        svcA.claim({ owner: 'worker-A' }),
+        svcB.claim({ owner: 'worker-B' }),
+      ]);
+
+      const winners = [a, b].filter((c) => c !== null);
+      expect(winners).toHaveLength(1);
+      expect(winners[0]!.id).toBe('only');
+      expect(winners[0]!.status).toBe('claimed');
+      expect(['worker-A', 'worker-B']).toContain(winners[0]!.claimOwner);
+
+      const card = await svc.get('only');
+      expect(card!.status).toBe('claimed');
+      expect(card!.attempts).toBe(1);
+    });
+
+    it('many concurrent claimers on N cards => no card is double-claimed', async () => {
+      // 5 ready cards, 8 concurrent claimers. Exactly 5 win, all distinct.
+      for (let i = 0; i < 5; i++) {
+        await svc.create({ id: `card-${i}`, title: `card ${i}`, priority: i });
+      }
+      const claimers = Array.from({ length: 8 }, (_, i) =>
+        new BacklogService(handle.db).claim({ owner: `w-${i}` }),
+      );
+      const results = await Promise.all(claimers);
+      const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
+      const wonIds = won.map((c) => c.id);
+      expect(won).toHaveLength(5);
+      expect(new Set(wonIds).size).toBe(5); // all distinct — no double-claim
+    });
+
+    it('N concurrent claimers on N ready cards => every claimer wins a distinct card (no starvation)', async () => {
+      // This is the direct benefit of locking exactly ONE ready row per claim
+      // (`FOR UPDATE SKIP LOCKED LIMIT 1`): with as many ready cards as
+      // claimers, NONE should starve. The old "lock the whole ready set"
+      // behaviour let one claimer lock every row, forcing the rest to null even
+      // though cards were free.
+      const N = 6;
+      for (let i = 0; i < N; i++) {
+        await svc.create({ id: `n-${i}`, title: `card ${i}`, priority: i });
+      }
+      const results = await Promise.all(
+        Array.from({ length: N }, (_, i) =>
+          new BacklogService(handle.db).claim({ owner: `w-${i}` }),
+        ),
+      );
+      const won = results.filter((c): c is NonNullable<typeof c> => c !== null);
+      // No claimer starved: all N won.
+      expect(won).toHaveLength(N);
+      // Each won a distinct card.
+      expect(new Set(won.map((c) => c.id)).size).toBe(N);
+      // Every ready card was consumed.
+      expect(await svc.list({ status: 'ready' })).toHaveLength(0);
+    });
+
+    it('sequential claims drain ready cards in priority order and never null while ready remain', async () => {
+      // PGlite-stable fallback assertion of the same property without relying on
+      // true parallelism or wall-clock timing: each claim returns the next
+      // highest-priority distinct card and never spuriously returns null while
+      // ready cards remain.
+      const N = 4;
+      for (let i = 0; i < N; i++) {
+        await svc.create({ id: `s-${i}`, title: `card ${i}`, priority: i });
+      }
+      const order: string[] = [];
+      for (let i = 0; i < N; i++) {
+        const claimed = await svc.claim({ owner: `w-${i}` });
+        expect(claimed).not.toBeNull();
+        order.push(claimed!.id);
+      }
+      // Highest priority first, all distinct.
+      expect(order).toEqual(['s-3', 's-2', 's-1', 's-0']);
+      expect(new Set(order).size).toBe(N);
+      // Now nothing ready remains => null.
+      expect(await svc.claim({ owner: 'late' })).toBeNull();
+    });
+
+    it('claim picks the highest-priority ready card', async () => {
+      await svc.create({ id: 'low', title: 'low', priority: 1 });
+      await svc.create({ id: 'high', title: 'high', priority: 9 });
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed!.id).toBe('high');
+    });
+
+    it('claim of a specific --id', async () => {
+      await svc.create({ id: 'a', title: 'a', priority: 9 });
+      await svc.create({ id: 'b', title: 'b', priority: 1 });
+      const claimed = await svc.claim({ owner: 'w', id: 'b' });
+      expect(claimed!.id).toBe('b');
+    });
+
+    it('claim returns null when nothing is ready', async () => {
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed).toBeNull();
+    });
+  });
+
+  describe('deps DAG gate', () => {
+    it('card with an unfinished dep is not claimable and not ready', async () => {
+      await svc.create({ id: 'dep', title: 'dependency' });
+      await svc.create({ id: 'main', title: 'depends on dep', dependsOn: ['dep'] });
+
+      // `main` should NOT be claimable while `dep` is not done — `dep` wins.
+      const first = await svc.claim({ owner: 'w' });
+      expect(first!.id).toBe('dep');
+
+      // With dep claimed (not done), main still cannot be claimed.
+      const second = await svc.claim({ owner: 'w' });
+      expect(second).toBeNull();
+
+      // ready-only list excludes main while its dep is unfinished.
+      const ready = await svc.list({ readyOnly: true });
+      expect(ready.map((c) => c.id)).not.toContain('main');
+
+      // Once dep is done, main becomes ready and claimable.
+      await svc.complete('dep');
+      const readyAfter = await svc.list({ readyOnly: true });
+      expect(readyAfter.map((c) => c.id)).toContain('main');
+      const third = await svc.claim({ owner: 'w' });
+      expect(third!.id).toBe('main');
+    });
+
+    it('link adds a depends_on edge', async () => {
+      await svc.create({ id: 'a', title: 'a' });
+      await svc.create({ id: 'b', title: 'b' });
+      const linked = await svc.link('a', 'b');
+      expect(linked.dependsOn).toEqual(['b']);
+      // a is now gated on b
+      const claimed = await svc.claim({ owner: 'w' });
+      expect(claimed!.id).toBe('b');
+    });
+  });
+
+  describe('reclaim TTL', () => {
+    it('reclaim returns expired claims to ready', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      const claimed = await svc.claim({ owner: 'w', ttlSeconds: 60 });
+      expect(claimed!.status).toBe('claimed');
+
+      // Backdate the claim so it is well past its TTL.
+      await handle.db.execute(sqlBackdate('c1'));
+
+      const result = await svc.reclaim();
+      expect(result.reclaimed).toEqual(['c1']);
+      const card = await svc.get('c1');
+      expect(card!.status).toBe('ready');
+      expect(card!.claimOwner).toBeNull();
+      expect(card!.claimedAt).toBeNull();
+    });
+
+    it('reclaim does not touch a fresh (unexpired) claim', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      await svc.claim({ owner: 'w', ttlSeconds: 3600 });
+      const result = await svc.reclaim();
+      expect(result.reclaimed).toEqual([]);
+      expect((await svc.get('c1'))!.status).toBe('claimed');
+    });
+
+    it('reclaim --id releases a specific claim regardless of expiry', async () => {
+      await svc.create({ id: 'c1', title: 'c1' });
+      await svc.claim({ owner: 'w', ttlSeconds: 3600 });
+      const result = await svc.reclaim({ id: 'c1' });
+      expect(result.reclaimed).toEqual(['c1']);
+      expect((await svc.get('c1'))!.status).toBe('ready');
+    });
+  });
+
+  describe('stats', () => {
+    it('computes counts, oldest-ready age, and expired-claim count', async () => {
+      await svc.create({ id: 'r1', title: 'r1' });
+      await svc.create({ id: 'r2', title: 'r2' });
+      await svc.create({ id: 'b1', title: 'b1' });
+      await svc.block('b1');
+      await svc.create({ id: 'd1', title: 'd1' });
+      await svc.complete('d1');
+      await svc.create({ id: 'cl1', title: 'cl1' });
+      await svc.claim({ owner: 'w', id: 'cl1', ttlSeconds: 60 });
+      await handle.db.execute(sqlBackdate('cl1'));
+
+      const stats = await svc.stats();
+      expect(stats.counts.ready).toBe(2);
+      expect(stats.counts.blocked).toBe(1);
+      expect(stats.counts.done).toBe(1);
+      expect(stats.counts.claimed).toBe(1);
+      expect(stats.total).toBe(5);
+      expect(stats.expiredClaimCount).toBe(1);
+      expect(stats.oldestReadyAgeSeconds).not.toBeNull();
+      expect(stats.oldestReadyAgeSeconds!).toBeGreaterThanOrEqual(0);
+    });
+  });
+});

packages/db/src/backlog.ts

@@ -0,0 +1,457 @@
+/**
+ * Mosaic-native backlog-of-record service (card A4).
+ *
+ * This is the backlog Mosaic owns end-to-end on its OWN Postgres storage layer.
+ * It REPLACES the former Hermes adapter — there is NO runtime dependency on
+ * Hermes here or anywhere downstream.
+ *
+ * The service takes a `Db` handle, so it works identically against:
+ *   - `createDb()`        — server Postgres (DATABASE_URL / config), and
+ *   - `createPgliteDb()`  — embedded Postgres (file or in-memory).
+ * Same code, same semantics — PGlite gives real Postgres behaviour (including
+ * row locks), so the atomic-claim path is exercised by the in-memory tests.
+ *
+ * Atomic claim: `claim()` selects the highest-priority, deps-satisfied, ready
+ * card with `SELECT ... FOR UPDATE SKIP LOCKED` and flips it to `claimed` inside
+ * one transaction. Two concurrent claimers can therefore NEVER both win the same
+ * card — the loser's locked row is skipped and it picks the next candidate (or
+ * gets null).
+ */
+
+import { and, asc, desc, eq, sql } from 'drizzle-orm';
+import type { Db } from './client.js';
+import { backlog } from './schema.js';
+
+export type BacklogStatus = 'ready' | 'claimed' | 'blocked' | 'done';
+
+export interface BacklogCard {
+  id: string;
+  title: string;
+  body: string | null;
+  phase: string | null;
+  priority: number;
+  status: BacklogStatus;
+  dependsOn: string[];
+  claimOwner: string | null;
+  claimTtlSeconds: number | null;
+  claimedAt: Date | null;
+  attempts: number;
+  idempotencyKey: string | null;
+  acceptance: unknown;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+export interface CreateCardInput {
+  id: string;
+  title: string;
+  body?: string | null;
+  phase?: string | null;
+  priority?: number;
+  dependsOn?: string[];
+  acceptance?: unknown;
+  idempotencyKey?: string | null;
+  status?: BacklogStatus;
+}
+
+export interface ListFilter {
+  status?: BacklogStatus;
+  phase?: string;
+  /** When true, return only cards that are `ready` AND have all deps `done`. */
+  readyOnly?: boolean;
+}
+
+export interface ClaimOptions {
+  owner: string;
+  /** Claim time-to-live in seconds (default 900). */
+  ttlSeconds?: number;
+  /** Claim a specific card by id instead of the highest-priority ready one. */
+  id?: string;
+}
+
+export interface ReclaimResult {
+  reclaimed: string[];
+}
+
+export interface BacklogStats {
+  counts: Record<BacklogStatus, number>;
+  total: number;
+  oldestReadyAgeSeconds: number | null;
+  expiredClaimCount: number;
+}
+
+export const DEFAULT_CLAIM_TTL_SECONDS = 900;
+
+type Row = typeof backlog.$inferSelect;
+
+/**
+ * Row shape as returned by the raw `SELECT * ... FOR UPDATE SKIP LOCKED` path.
+ * That path bypasses drizzle's column-name mapping, so JSON columns arrive as
+ * the snake_case `depends_on` (and may be a JSON string under some drivers).
+ */
+interface RawRow extends Row {
+  depends_on?: unknown;
+}
+
+function toCard(row: Row): BacklogCard {
+  return {
+    id: row.id,
+    title: row.title,
+    body: row.body,
+    phase: row.phase,
+    priority: row.priority,
+    status: row.status,
+    dependsOn: row.dependsOn ?? [],
+    claimOwner: row.claimOwner,
+    claimTtlSeconds: row.claimTtlSeconds,
+    claimedAt: row.claimedAt,
+    attempts: row.attempts,
+    idempotencyKey: row.idempotencyKey,
+    acceptance: row.acceptance,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+/**
+ * The backlog repository/service. Construct with any `Db` handle.
+ */
+export class BacklogService {
+  constructor(private readonly db: Db) {}
+
+  /**
+   * Create a card. If `idempotencyKey` is provided and a card already exists
+   * with that key, the existing card is returned unchanged (no duplicate).
+   */
+  async create(input: CreateCardInput): Promise<BacklogCard> {
+    if (input.idempotencyKey) {
+      const existing = await this.db
+        .select()
+        .from(backlog)
+        .where(eq(backlog.idempotencyKey, input.idempotencyKey))
+        .limit(1);
+      if (existing[0]) return toCard(existing[0]);
+    }
+
+    const inserted = await this.db
+      .insert(backlog)
+      .values({
+        id: input.id,
+        title: input.title,
+        body: input.body ?? null,
+        phase: input.phase ?? null,
+        priority: input.priority ?? 0,
+        status: input.status ?? 'ready',
+        dependsOn: input.dependsOn ?? [],
+        acceptance: input.acceptance ?? null,
+        idempotencyKey: input.idempotencyKey ?? null,
+      })
+      .returning();
+
+    return toCard(inserted[0]!);
+  }
+
+  /** Fetch a single card by id, or null. */
+  async get(id: string): Promise<BacklogCard | null> {
+    const rows = await this.db.select().from(backlog).where(eq(backlog.id, id)).limit(1);
+    return rows[0] ? toCard(rows[0]) : null;
+  }
+
+  /**
+   * List cards with optional filters. `readyOnly` enforces the DAG gate:
+   * a card is "ready" only when its own status is `ready` AND every card in
+   * `depends_on` exists and is `done`.
+   */
+  async list(filter: ListFilter = {}): Promise<BacklogCard[]> {
+    const conditions = [];
+    if (filter.status) conditions.push(eq(backlog.status, filter.status));
+    if (filter.phase) conditions.push(eq(backlog.phase, filter.phase));
+
+    const rows = await this.db
+      .select()
+      .from(backlog)
+      .where(conditions.length ? and(...conditions) : undefined)
+      .orderBy(desc(backlog.priority), asc(backlog.createdAt));
+
+    const cards = rows.map(toCard);
+    if (!filter.readyOnly) return cards;
+
+    const doneIds = await this.doneIdSet();
+    return cards.filter(
+      (c) => c.status === 'ready' && c.dependsOn.every((dep) => doneIds.has(dep)),
+    );
+  }
+
+  private async doneIdSet(): Promise<Set<string>> {
+    const done = await this.db
+      .select({ id: backlog.id })
+      .from(backlog)
+      .where(eq(backlog.status, 'done'));
+    return new Set(done.map((d) => d.id));
+  }
+
+  /**
+   * Atomically claim a card.
+   *
+   * Strategy: inside ONE transaction we lock the candidate row with
+   * `FOR UPDATE SKIP LOCKED LIMIT 1`. A concurrent claimer that already holds
+   * the lock on a row has that row skipped for us, so two claimers can never
+   * both win the same card — and, crucially, each claimer locks exactly ONE
+   * row, so concurrent claimers fan out across distinct ready cards instead of
+   * one claimer locking the whole ready set and starving the rest.
+   *
+   * Candidate selection (when no explicit `id`):
+   *   - status = 'ready'
+   *   - all deps satisfied (every id in depends_on is currently 'done')
+   *   - ordered by priority DESC, created_at ASC
+   *
+   * Returns the claimed card, or null if nothing is claimable.
+   */
+  async claim(opts: ClaimOptions): Promise<BacklogCard | null> {
+    const ttl = opts.ttlSeconds ?? DEFAULT_CLAIM_TTL_SECONDS;
+
+    return this.db.transaction(async (tx) => {
+      // Specific-id path: lock that one ready row (if free) and apply the
+      // deps-satisfied gate in JS, exactly as before.
+      if (opts.id) {
+        const doneRows = await tx
+          .select({ id: backlog.id })
+          .from(backlog)
+          .where(eq(backlog.status, 'done'));
+        const doneIds = new Set(doneRows.map((r) => r.id));
+
+        const result = await tx.execute(
+          sql`SELECT * FROM ${backlog}
+              WHERE ${backlog.id} = ${opts.id} AND ${backlog.status} = 'ready'
+              FOR UPDATE SKIP LOCKED`,
+        );
+        const candidate = rowsOf(result).find((row) =>
+          normalizeDeps(row.depends_on).every((dep) => doneIds.has(dep)),
+        );
+        if (!candidate) return null;
+
+        const updated = await tx
+          .update(backlog)
+          .set({
+            status: 'claimed',
+            claimOwner: opts.owner,
+            claimTtlSeconds: ttl,
+            claimedAt: new Date(),
+            attempts: sql`${backlog.attempts} + 1`,
+            updatedAt: new Date(),
+          })
+          .where(eq(backlog.id, candidate.id))
+          .returning();
+
+        return toCard(updated[0]!);
+      }
+
+      // No-id path: claim the single highest-priority, deps-satisfied ready
+      // card. We lock exactly ONE row in the inner SELECT (`FOR UPDATE SKIP
+      // LOCKED LIMIT 1`) so concurrent claimers grab distinct cards rather than
+      // one claimer locking every ready row and forcing the others to null.
+      //
+      // The deps-satisfied gate is pushed into SQL so `LIMIT 1` lands on the
+      // next genuinely-eligible card: a card is eligible iff none of its
+      // depends_on ids is absent from the set of 'done' card ids.
+      const updated = await tx.execute(
+        sql`UPDATE ${backlog}
+            SET status = 'claimed',
+                claim_owner = ${opts.owner},
+                claim_ttl_seconds = ${ttl},
+                claimed_at = now(),
+                attempts = ${backlog.attempts} + 1,
+                updated_at = now()
+            WHERE ${backlog.id} = (
+              SELECT b.id FROM ${backlog} AS b
+              WHERE b.status = 'ready'
+                AND NOT EXISTS (
+                  SELECT 1
+                  FROM jsonb_array_elements_text(b.depends_on) AS dep
+                  WHERE dep NOT IN (
+                    SELECT d.id FROM ${backlog} AS d WHERE d.status = 'done'
+                  )
+                )
+              ORDER BY b.priority DESC, b.created_at ASC
+              FOR UPDATE SKIP LOCKED
+              LIMIT 1
+            )
+            RETURNING *`,
+      );
+
+      const row = rowsOf(updated)[0];
+      return row ? toCard(rawToRow(row)) : null;
+    });
+  }
+
+  /**
+   * Release expired claims (claimed_at + ttl < now) back to `ready`, OR release
+   * a specific card by id regardless of expiry. Cleared claim fields.
+   * Returns the ids that were released.
+   */
+  async reclaim(opts: { id?: string } = {}): Promise<ReclaimResult> {
+    if (opts.id) {
+      const released = await this.db
+        .update(backlog)
+        .set({
+          status: 'ready',
+          claimOwner: null,
+          claimTtlSeconds: null,
+          claimedAt: null,
+          updatedAt: new Date(),
+        })
+        .where(and(eq(backlog.id, opts.id), eq(backlog.status, 'claimed')))
+        .returning({ id: backlog.id });
+      return { reclaimed: released.map((r) => r.id) };
+    }
+
+    // Expired = status claimed AND claimed_at + (ttl seconds) < now().
+    const released = await this.db
+      .update(backlog)
+      .set({
+        status: 'ready',
+        claimOwner: null,
+        claimTtlSeconds: null,
+        claimedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(
+        and(
+          eq(backlog.status, 'claimed'),
+          sql`${backlog.claimedAt} + make_interval(secs => ${backlog.claimTtlSeconds}) < now()`,
+        ),
+      )
+      .returning({ id: backlog.id });
+    return { reclaimed: released.map((r) => r.id) };
+  }
+
+  /** Add a `depends_on` edge (from → depends on → to). Idempotent. */
+  async link(from: string, to: string): Promise<BacklogCard> {
+    const card = await this.get(from);
+    if (!card) throw new Error(`backlog card not found: ${from}`);
+    const target = await this.get(to);
+    if (!target) throw new Error(`backlog dependency not found: ${to}`);
+    if (from === to) throw new Error('a card cannot depend on itself');
+
+    if (card.dependsOn.includes(to)) return card;
+    const nextDeps = [...card.dependsOn, to];
+    const updated = await this.db
+      .update(backlog)
+      .set({ dependsOn: nextDeps, updatedAt: new Date() })
+      .where(eq(backlog.id, from))
+      .returning();
+    return toCard(updated[0]!);
+  }
+
+  /** Mark a card blocked. */
+  async block(id: string): Promise<BacklogCard | null> {
+    return this.setStatus(id, 'blocked');
+  }
+
+  /** Mark a card done (releasing any claim). */
+  async complete(id: string): Promise<BacklogCard | null> {
+    const updated = await this.db
+      .update(backlog)
+      .set({
+        status: 'done',
+        claimOwner: null,
+        claimTtlSeconds: null,
+        claimedAt: null,
+        updatedAt: new Date(),
+      })
+      .where(eq(backlog.id, id))
+      .returning();
+    return updated[0] ? toCard(updated[0]) : null;
+  }
+
+  private async setStatus(id: string, status: BacklogStatus): Promise<BacklogCard | null> {
+    const updated = await this.db
+      .update(backlog)
+      .set({ status, updatedAt: new Date() })
+      .where(eq(backlog.id, id))
+      .returning();
+    return updated[0] ? toCard(updated[0]) : null;
+  }
+
+  /** Counts by status, oldest-ready age (seconds), and expired-claim count. */
+  async stats(): Promise<BacklogStats> {
+    const all = await this.db.select().from(backlog);
+    const counts: Record<BacklogStatus, number> = {
+      ready: 0,
+      claimed: 0,
+      blocked: 0,
+      done: 0,
+    };
+    let oldestReady: Date | null = null;
+    let expiredClaimCount = 0;
+    const now = Date.now();
+
+    for (const row of all) {
+      counts[row.status] += 1;
+      if (row.status === 'ready') {
+        if (oldestReady === null || row.createdAt < oldestReady) oldestReady = row.createdAt;
+      }
+      if (row.status === 'claimed' && row.claimedAt && row.claimTtlSeconds != null) {
+        const expiry = row.claimedAt.getTime() + row.claimTtlSeconds * 1000;
+        if (expiry < now) expiredClaimCount += 1;
+      }
+    }
+
+    return {
+      counts,
+      total: all.length,
+      oldestReadyAgeSeconds:
+        oldestReady === null ? null : Math.max(0, Math.floor((now - oldestReady.getTime()) / 1000)),
+      expiredClaimCount,
+    };
+  }
+}
+
+/** Extract rows from a drizzle `.execute()` result across drivers (pg / pglite). */
+function rowsOf(result: unknown): RawRow[] {
+  if (Array.isArray(result)) return result as RawRow[];
+  const maybe = result as { rows?: unknown };
+  if (maybe && Array.isArray(maybe.rows)) return maybe.rows as RawRow[];
+  return [];
+}
+
+/**
+ * Map a raw `RETURNING *` row (snake_case columns, possibly string-encoded
+ * timestamps/JSON depending on the driver) onto the drizzle `Row` shape that
+ * `toCard` consumes. Mirrors the column ↔ property mapping in `schema.ts`.
+ */
+function rawToRow(raw: RawRow): Row {
+  const r = raw as unknown as Record<string, unknown>;
+  const toDate = (v: unknown): Date => (v instanceof Date ? v : new Date(v as string));
+  return {
+    id: r.id as string,
+    title: r.title as string,
+    body: (r.body ?? null) as string | null,
+    phase: (r.phase ?? null) as string | null,
+    priority: Number(r.priority),
+    status: r.status as BacklogStatus,
+    dependsOn: normalizeDeps(r.depends_on),
+    claimOwner: (r.claim_owner ?? null) as string | null,
+    claimTtlSeconds: r.claim_ttl_seconds == null ? null : Number(r.claim_ttl_seconds),
+    claimedAt: r.claimed_at == null ? null : toDate(r.claimed_at),
+    attempts: Number(r.attempts),
+    idempotencyKey: (r.idempotency_key ?? null) as string | null,
+    acceptance: r.acceptance ?? null,
+    createdAt: toDate(r.created_at),
+    updatedAt: toDate(r.updated_at),
+  };
+}
+
+/** A raw SQL row returns snake_case `depends_on`; normalize to string[]. */
+function normalizeDeps(value: unknown): string[] {
+  if (Array.isArray(value)) return value as string[];
+  if (typeof value === 'string') {
+    try {
+      const parsed = JSON.parse(value);
+      return Array.isArray(parsed) ? (parsed as string[]) : [];
+    } catch {
+      return [];
+    }
+  }
+  return [];
+}

packages/db/src/index.ts

@@ -3,6 +3,17 @@ export { createPgliteDb } from './client-pglite.js';
 export { runMigrations, runPgliteMigrations } from './migrate.js';
 export * from './schema.js';
 export * from './federation.js';
+export {
+  BacklogService,
+  DEFAULT_CLAIM_TTL_SECONDS,
+  type BacklogCard,
+  type BacklogStatus,
+  type BacklogStats,
+  type ClaimOptions,
+  type CreateCardInput,
+  type ListFilter,
+  type ReclaimResult,
+} from './backlog.js';
 export {
   eq,
   and,

packages/db/src/schema.ts

@@ -587,6 +587,62 @@ export const summarizationJobs = pgTable(
   (t) => [index('summarization_jobs_status_idx').on(t.status)],
 );
 
+// ─── Fleet Backlog ────────────────────────────────────────────────────────────
+// Mosaic-native backlog-of-record (card A4). This REPLACES the former Hermes
+// adapter — there is NO runtime dependency on Hermes. Cards form a dependency
+// DAG (`depends_on`), are claimed atomically by fleet workers via
+// `SELECT ... FOR UPDATE SKIP LOCKED`, and auto-expire via a TTL so a crashed
+// claimer's card returns to the pool.
+
+/**
+ * Lifecycle status of a backlog card.
+ * - ready:   eligible to be claimed (once its deps are all `done`).
+ * - claimed: a worker holds it (claim_owner + claimed_at set); may expire via TTL.
+ * - blocked: explicitly parked; never auto-claimed.
+ * - done:    completed; satisfies dependents.
+ */
+export const backlogStatusEnum = pgEnum('backlog_status', ['ready', 'claimed', 'blocked', 'done']);
+
+export const backlog = pgTable(
+  'backlog',
+  {
+    /** Stable, caller-supplied card id (e.g. "A4", "fleet-001"). PK. */
+    id: text('id').primaryKey(),
+    title: text('title').notNull(),
+    body: text('body'),
+    /** Board/phase grouping (e.g. "M1", "fleet"). Free-form. */
+    phase: text('phase'),
+    /** Higher number = higher priority; claim picks the max-priority ready card. */
+    priority: integer('priority').notNull().default(0),
+    status: backlogStatusEnum('status').notNull().default('ready'),
+    /** DAG edges: ids of cards this one depends on. "ready" requires all done. */
+    dependsOn: jsonb('depends_on').notNull().$type<string[]>().default([]),
+    /** Owner token of the current claim (worker/agent id). NULL when unclaimed. */
+    claimOwner: text('claim_owner'),
+    /** TTL of the active claim in seconds. NULL when unclaimed. */
+    claimTtlSeconds: integer('claim_ttl_seconds'),
+    /** When the active claim was taken. NULL when unclaimed. claimed_at + ttl = expiry. */
+    claimedAt: timestamp('claimed_at', { withTimezone: true }),
+    /** Count of times this card has been claimed (incremented on each claim). */
+    attempts: integer('attempts').notNull().default(0),
+    /** Optional dedup key for `create`; a repeat key returns the existing card. */
+    idempotencyKey: text('idempotency_key'),
+    /** Acceptance criteria — free-form JSON (array of strings or object). */
+    acceptance: jsonb('acceptance'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    // Hot path: claim scans ready cards ordered by priority then age.
+    index('backlog_status_priority_idx').on(t.status, t.priority),
+    // reclaim sweeps claimed cards by claimed_at to find expired ones.
+    index('backlog_status_claimed_at_idx').on(t.status, t.claimedAt),
+    // Idempotent create dedups on this key (NULLs are distinct in Postgres, so
+    // many unkeyed cards coexist; a repeated non-null key collides).
+    uniqueIndex('backlog_idempotency_key_idx').on(t.idempotencyKey),
+  ],
+);
+
 // ─── Federation ──────────────────────────────────────────────────────────────
 // Enums declared before tables that reference them.
 // All federation definitions live in this file (avoids CJS/ESM cross-import

packages/mosaic/framework/fleet/roles/board.md

@@ -0,0 +1,38 @@
+# Board — fleet role definition
+
+The **board** is the fleet's **deliberation panel** (`class: board`). It is the
+forge **Board-of-Directors** reused as a fleet role — a multi-lens review body
+(moonshot, contrarian, technical, business, financial) that owns the mission's
+direction, not its execution.
+
+It is a **front-office** role: it sets and guards intent, then steps back.
+
+## Mandate
+
+1. **Own `NORTH_STAR.yaml`** — the single source of truth for goals, assumptions,
+   and projections. The board is the only role that ratifies edits to it.
+2. **Ratify or veto goals and assumptions** — every new objective or load-bearing
+   assumption passes the board's lenses before the fleet commits resources to it.
+3. **Hold the lenses** — moonshot (is the ambition right?), contrarian (what breaks
+   this?), technical (is it buildable?), business (does it matter?), financial
+   (can we afford it, in tokens and dollars?).
+4. **Re-deliberate on drift** — when results diverge from the north star, the board
+   reconvenes, re-ratifies or vetoes, and updates `NORTH_STAR.yaml`.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT decompose, plan phases, or dispatch tasks** — it ratifies the
+  _what_ and _why_; planner and decomposition own the _how_.
+
+The board deliberates and decides direction; it never touches the working tree or
+the merge path. When it approves a goal, the planner expands it.
+
+## Persona
+
+A standing panel of senior voices, each arguing from a fixed vantage. The board is
+deliberately slow and adversarial — its value is catching the expensive mistake
+before a single agent-hour is spent on it.
+
+> Doctrine: `docs/fleet/north-star.md` ('board' role = forge BOD; role library).

packages/mosaic/framework/fleet/roles/code.md

@@ -0,0 +1,36 @@
+# Code — fleet role definition
+
+The **code** role is the fleet's primary **executor** (`class: code`). It picks up
+one decomposition card and implements it to green CI on a branch, then opens a PR.
+
+It is an **execution** role: one card, one branch, one PR.
+
+## Mandate
+
+1. **Implement one card to green CI** — take a single backlog card and make the
+   change it describes, on a dedicated branch, until the project's gates
+   (typecheck, lint, format, tests) pass.
+2. **Open the PR via `pr-create.sh`** — once gates are green, open exactly one
+   pull request for the card using the standard `pr-create.sh` wrapper.
+3. **Stay in card scope** — touch only the files the card calls for. No scope
+   creep, no opportunistic refactors outside the card's boundary.
+4. **One card = one PR** — honor the decomposition contract: a card becomes a
+   single focused PR, never two, and a PR never bundles two cards.
+
+## Boundaries
+
+- **Does NOT merge.** Opening the PR is the end of the code role's authority; the
+  **merge-gate** role is the only approver/merger.
+- **Does NOT approve or self-review** — correctness sign-off belongs to the
+  **review** and **security-review** roles.
+- **Does NOT decompose or re-plan** — if a card is wrong or too large, it escalates
+  rather than silently re-scoping.
+
+The code role writes the change and opens the PR; it never touches the merge path.
+
+## Persona
+
+The focused builder. It takes one well-scoped card, drives it to green, opens a
+clean PR, and hands off — never reaching past the card it was given.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/decomposition.md

@@ -0,0 +1,38 @@
+# Decomposition — fleet role definition
+
+The **decomposition** role splits the planner's FRs into **one-PR-each cards**,
+wired together with `depends_on` link edges, ready for the code role to pick up.
+
+It is a **front-office** role.
+
+## Mandate
+
+1. **Drive the native `mosaic fleet backlog`** — decomposition is the operator of
+   Mosaic's own backlog; it creates and links cards there, on Mosaic's storage
+   layer. It does NOT hand-roll a parallel splitter and does NOT call any external
+   kanban service.
+2. **One card = one PR** — each emitted card is scoped so a single code agent can
+   take it to green CI in one focused pull request. No card spans two PRs; no PR
+   spans two cards.
+3. **Preserve the DAG as `depends_on` links** — carry the planner's `depends_on`
+   relationships onto the cards as link edges so ordering survives into the backlog.
+4. **Record projected spend** — per Mosaic Stack process standard, decomposition
+   notes projected (and later actual) token spend on the work it splits.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT start work** — it produces cards and stops. Picking up a card and
+  implementing it is the **code** role's job.
+
+Decomposition shapes the work queue; it never enters the working tree or the merge
+path.
+
+## Persona
+
+The work-breakdown specialist. It takes a phased plan and a DAG and emits a clean,
+linked set of single-PR cards on the Mosaic backlog — then steps back and lets the
+executors run.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); spend accounting is a process mandate.

packages/mosaic/framework/fleet/roles/documentation.md

@@ -0,0 +1,39 @@
+# Documentation — fleet role definition
+
+The **documentation** role is the fleet's **prose maintainer**
+(`class: documentation`). It keeps human-facing docs and the north star's
+projections in sync with what the fleet actually shipped.
+
+It is an **execution** role: docs and projections, not product code.
+
+## Mandate
+
+1. **Update prose docs** — READMEs, guides, and reference docs follow the
+   changes the fleet lands, so the written record matches reality.
+2. **Update `NORTH_STAR.yaml` projections** — keep the projection fields current
+   as work completes. (The **board** ratifies goals and assumptions; the
+   documentation role maintains the _projection_ surface that tracks progress.)
+3. **Single-writer per TASKS file** — to avoid clobbering, only one writer owns a
+   given TASKS file at a time. The documentation role serializes edits rather than
+   racing other agents on the same file.
+4. **Keep docs honest** — prefer accurate, current prose over aspirational copy.
+
+## Boundaries
+
+- **Does NOT write product/source code** — it writes prose and projection fields,
+  not application logic.
+- **Does NOT merge.** Doc changes go through the same PR + **merge-gate** path as
+  any other change.
+- **Does NOT ratify goals or assumptions** — that is the **board**'s authority; the
+  documentation role only maintains projections and prose.
+
+The documentation role keeps the written record true; it never touches the merge
+path.
+
+## Persona
+
+The scribe of record. It makes sure the docs and the north star's projections
+describe the system as it actually is, and it never lets two writers fight over one
+TASKS file.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/merge-gate.md

@@ -0,0 +1,42 @@
+# Merge-gate — fleet role definition
+
+The **merge-gate** is the fleet's **sole approver and auto-merger**
+(`class: merge-gate`). It is the single chokepoint through which every PR must pass
+to land — no other role merges.
+
+It is a **gate** role: the one and only merge path.
+
+## Mandate
+
+1. **Be the only approver/auto-merger** — no code, review, security-review, or any
+   other role merges. Approval-to-land flows through the merge-gate alone.
+2. **Use the wrapped scripts as the ONLY merge path** — the merge-gate merges
+   **exclusively** by calling **`pr-merge.sh`** (the merge action, which carries the
+   authoritative forbidden-path guard) and **`pr-ci-wait.sh`** (to wait for green
+   CI before merging). These two scripts are the _only_ sanctioned merge path.
+3. **Never call the raw API** — the merge-gate **does NOT** call `tea`, the raw
+   Gitea/forge HTTP API, or any other merge mechanism directly. Only `pr-merge.sh`
+   and `pr-ci-wait.sh`.
+4. **Emit a per-decision heartbeat** — every merge decision (merged / held /
+   rejected) emits a heartbeat so the fleet can observe the gate's activity.
+5. **Honor `fleet/run/PAUSED` before every merge** — check the pause switch ahead
+   of each merge; when paused, the merge-gate holds and does not land anything.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT decompose, plan, or author changes** — it only decides whether an
+  already-reviewed PR lands.
+- **Does NOT merge via any path other than `pr-merge.sh` + `pr-ci-wait.sh`** — no
+  raw `tea`/Gitea API, ever.
+
+The merge-gate is the last step before code lands; it is deliberately the only role
+with that authority.
+
+## Persona
+
+The single, accountable gatekeeper. It waits for green CI (`pr-ci-wait.sh`),
+respects the pause switch, merges only through `pr-merge.sh`, and records every
+decision — so the fleet has exactly one trustworthy door to production.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); merge path: `pr-merge.sh` + `pr-ci-wait.sh`; forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/operator.md

@@ -0,0 +1,38 @@
+# Operator — fleet role definition
+
+The **operator** is the fleet's **escalation and control surface**
+(`class: operator`). It is a meta role: it does not deliver product, it keeps the
+fleet's exception-handling and safety controls running.
+
+It is a **meta** role: control plane, not delivery.
+
+## Mandate
+
+1. **Consume escalations** — it is the destination for escalations raised by other
+   roles (e.g. the **rebase** role's genuine conflicts, blocked work, stuck cards).
+2. **Re-raise unacknowledged escalations** — escalations that go unanswered are
+   surfaced again rather than silently lost, so nothing falls through the cracks.
+3. **Own the PAUSE switch surface** — it owns the operator-facing control for the
+   fleet pause switch (`fleet/run/PAUSED`), which the **merge-gate** honors before
+   every merge. The operator can pause and resume the fleet.
+4. **Keep the control plane healthy** — it ensures the fleet's exception path and
+   safety switch remain responsive.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.** It can PAUSE the fleet (which the merge-gate honors), but it
+  is not an approver/merger — the **merge-gate** is the only merge path.
+- **Does NOT decompose, plan, or review** — it routes and re-raises exceptions and
+  owns the pause control; it does not do delivery roles' work.
+
+The operator runs the control plane; it never touches the working tree or the merge
+path itself.
+
+## Persona
+
+The on-call dispatcher. It makes sure every escalation is seen and re-seen until
+handled, and it holds the one switch that can stop the fleet when something is
+wrong.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); pause switch: `fleet/run/PAUSED`.

packages/mosaic/framework/fleet/roles/planner.md

@@ -0,0 +1,40 @@
+# Planner — fleet role definition
+
+The **planner** turns ratified objectives into an executable **plan** — phased
+functional requirements (FRs) wired into a `depends_on` DAG.
+
+> **Alias:** the planner role IS the existing **orchestrator** class. The
+> orchestrator _plays_ planner; this file documents the planning contract, it does
+> **not** introduce a competing class. The two-agent floor (orchestrator +
+> enhancer) is preserved — do not split planner into a separate persistent agent
+> that would break it.
+
+It is a **front-office** role.
+
+## Mandate
+
+1. **Expand objectives into phased FRs** — take a board-ratified goal and break it
+   into functional requirements, grouped into phases.
+2. **Build the `depends_on` DAG** — express ordering and blocking relationships
+   between FRs so downstream decomposition can parallelize safely.
+3. **Emit a plan, not tasks** — the planner's output is the phased FR/DAG
+   document. Splitting FRs into one-PR-each cards is the **decomposition** role's job.
+4. **Re-plan on failure** — when execution diverges, the planner (orchestrator)
+   re-sequences the DAG rather than letting agents improvise.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT emit cards** — it stops at the plan (FRs + DAG); decomposition
+  converts the plan into work items.
+
+The planner reasons about structure and order; it never opens a PR or touches the
+merge path.
+
+## Persona
+
+The architect of the mission's shape. It thinks in phases and dependencies, hands
+a clean DAG to decomposition, and keeps the orchestrator/enhancer floor intact.
+
+> Doctrine: `docs/fleet/north-star.md` (two-agent floor + role library).

packages/mosaic/framework/fleet/roles/rebase.md

@@ -0,0 +1,37 @@
+# Rebase — fleet role definition
+
+The **rebase** role is the fleet's **freshness keeper** (`class: rebase`). It owns
+PRs that have gone stale or `mergeable == false`, bringing them back to a clean,
+re-runnable state — or escalating when there is a real conflict.
+
+It is an **execution** role: it operates on existing PR branches.
+
+## Mandate
+
+1. **Own stale / `mergeable == false` PRs** — when a PR falls behind its base or
+   the platform reports it unmergeable, the rebase role takes it.
+2. **Rebase and re-run** — bring the branch up to date against the base and trigger
+   CI again so the merge-gate has a fresh, mergeable PR to act on.
+3. **Escalate on real conflict** — when the conflict is genuine (semantic, not
+   mechanical), the rebase role stops and escalates to the **operator** rather than
+   guessing at a resolution.
+4. **Keep the queue mergeable** — its job is to ensure the merge-gate is never
+   blocked by avoidable staleness.
+
+## Boundaries
+
+- **Does NOT merge.** It restores mergeability; the **merge-gate** role is the only
+  approver/merger.
+- **Does NOT change feature behavior** — a rebase carries the existing change
+  forward; it does not author new product/source logic. Behavioral fixes go back to
+  the **code** role.
+- **Does NOT force-resolve genuine conflicts** — it escalates them.
+
+The rebase role keeps PR branches fresh; it never approves or merges.
+
+## Persona
+
+The janitor of the merge queue. It quietly keeps branches current and re-runnable,
+and knows when a conflict is beyond a mechanical rebase and must be escalated.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/review.md

@@ -0,0 +1,38 @@
+# Review — fleet role definition
+
+The **review** role is the fleet's **correctness reviewer** (`class: review`). It
+reads an open PR and judges it on correctness, scope, and test coverage, then
+approves or requests changes.
+
+It is an **execution** role: one open PR per pass.
+
+## Mandate
+
+1. **Judge correctness** — does the change do what its card says, correctly, without
+   introducing regressions?
+2. **Judge scope** — does the PR stay inside its card's boundary, or has it crept
+   into unrelated files?
+3. **Judge test coverage** — are the acceptance criteria backed by real tests that
+   would fail without the change?
+4. **Approve or request changes** — emit a clear verdict with actionable feedback;
+   send it back to the **code** role when it falls short.
+
+## Boundaries
+
+- **Does NOT merge.** Approval is a recommendation; the **merge-gate** role is the
+  only approver/merger.
+- **Does NOT write product/source code** — it reviews; it does not author the fix.
+  Remediation goes back to the **code** role.
+- **Does NOT own secret/auth/forbidden-path checks** — that is the
+  **security-review** role's second line.
+
+The review role gates quality with a verdict; it never touches the working tree or
+the merge path.
+
+## Persona
+
+The careful reader. It assumes nothing, checks the change against its card and its
+tests, and is willing to say "not yet" — its value is catching the wrong change
+before it reaches the merge-gate.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/fleet/roles/security-review.md

@@ -0,0 +1,39 @@
+# Security-review — fleet role definition
+
+The **security-review** role is the fleet's **second line of review**
+(`class: security-review`). Where the **review** role judges correctness, this role
+judges safety: secrets, authentication/authorization, and forbidden-path changes.
+
+It is an **execution** role: one open PR per pass.
+
+## Mandate
+
+1. **Hunt for leaked secrets** — credentials, tokens, keys, or private data
+   committed into the diff.
+2. **Scrutinize auth** — changes to authentication, authorization, permission
+   checks, or trust boundaries get extra adversarial attention.
+3. **Enforce forbidden paths** — flag edits to protected files/areas. The
+   **authoritative forbidden-path list lives in code** — the `pr-merge.sh` guard —
+   not in this prompt. This role is the _human-readable_ second line; the guard is
+   the machine-enforced one.
+4. **Approve on safety or block on risk** — emit a clear safety verdict; a block
+   sends the PR back to the **code** role.
+
+## Boundaries
+
+- **Does NOT merge.** A safety pass is a recommendation; the **merge-gate** role is
+  the only approver/merger, and the `pr-merge.sh` guard is the enforced gate.
+- **Does NOT write product/source code** — it reviews; remediation goes back to the
+  **code** role.
+- **Does NOT redefine the forbidden-path list** — it defers to the `pr-merge.sh`
+  guard as the source of truth.
+
+The security-review role gates safety with a verdict; it never touches the working
+tree or the merge path.
+
+## Persona
+
+The adversary on your side. It reads every diff asking "how does this get exploited
+or leak?" — the second, security-focused pair of eyes before the merge-gate.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); forbidden paths: `pr-merge.sh` guard.

packages/mosaic/framework/fleet/roles/session-review.md

@@ -0,0 +1,37 @@
+# Session-review — fleet role definition
+
+The **session-review** role runs the fleet's **post-task retrospective**
+(`class: session-review`). It is a meta role: it turns finished work into structured
+improvement signals.
+
+It is a **meta** role: learning, not delivery.
+
+## Mandate
+
+1. **Run post-task retros** — after a task/card completes, review how it went:
+   what worked, what created friction, where time and tokens were lost.
+2. **Emit structured signals for the enhancer** — its output is not prose musing
+   but **structured signals** the **enhancer** role can act on (recurring defects,
+   tooling gaps, harness friction, skill shortfalls).
+3. **Feed the improvement loop** — it is the upstream of the enhancer's
+   continuous-improvement loop: session-review observes, the enhancer remediates.
+4. **Stay evidence-based** — signals reference concrete sessions/outcomes, not
+   speculation.
+
+## Boundaries
+
+- **Does NOT write product/source code.**
+- **Does NOT merge.**
+- **Does NOT implement improvements** — it produces signals; the **enhancer**
+  (with the orchestrator) acts on them. Session-review diagnoses; it does not fix.
+
+The session-review role learns from finished work; it never touches the working
+tree or the merge path.
+
+## Persona
+
+The retrospective analyst. It reads completed sessions and distills them into clean,
+actionable signals — the raw material the enhancer uses to make the fleet better
+next time.
+
+> Doctrine: `docs/fleet/north-star.md` (role library); consumed by the enhancer role.

packages/mosaic/framework/fleet/roles/site-tester.md

@@ -0,0 +1,37 @@
+# Site-tester — fleet role definition
+
+The **site-tester** role is the fleet's **runtime verifier** (`class: site-tester`).
+Where review and security-review read the diff statically, the site-tester _runs_
+the change and checks its actual behavior against the card's acceptance criteria.
+
+It is an **execution** role: behavioral verification per PR/card.
+
+## Mandate
+
+1. **Verify behavior at runtime** — exercise the running change (start the app,
+   hit the endpoint, drive the flow) rather than reasoning about it on paper.
+2. **Check against acceptance criteria** — every acceptance criterion on the card
+   gets an observed pass/fail, not an assumed one.
+3. **Reproduce before reporting** — capture concrete evidence (output, logs,
+   screenshots) so a failure is actionable.
+4. **Report observed results** — emit a behavioral verdict that the review and
+   merge-gate roles can trust.
+
+## Boundaries
+
+- **Does NOT merge.** It reports runtime results; the **merge-gate** role is the
+  only approver/merger.
+- **Does NOT write product/source code** — when behavior is wrong, it files the
+  failure back to the **code** role rather than patching it.
+- **Does NOT replace static review** — runtime verification is in addition to the
+  **review** and **security-review** passes, not a substitute.
+
+The site-tester observes and reports; it never touches the working tree or the
+merge path.
+
+## Persona
+
+The skeptic who insists on running it. It trusts observed behavior over claimed
+behavior, and turns "should work" into "verified works" — or a concrete bug report.
+
+> Doctrine: `docs/fleet/north-star.md` (role library).

packages/mosaic/framework/install.sh

@@ -25,13 +25,17 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
 # User-created content in these paths survives rsync --delete.
 #
 # fleet/* — the framework SEEDS only fleet/examples, fleet/roles, and
-# fleet/roster.schema.json (synced normally). The user's own fleet files MUST
+# fleet/roster.schema.json (synced normally — every fleet/roles/*.md role contract
+# lands automatically via this sync, so no per-file entry is needed). The user's
+# own fleet files MUST
 # survive `mosaic update` (which runs this sync automatically): the active
 # roster (`fleet/roster.yaml` + any other `fleet/*.yaml`), per-agent env
-# (`fleet/agents/`), and heartbeat run dir (`fleet/run/`). Without these, an
-# update wipes the operator's fleet. Glob entries are honored by both the rsync
-# path (`--exclude`) and the glob-aware cp fallback below.
-PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run")
+# (`fleet/agents/`), heartbeat run dir (`fleet/run/`), and the Mosaic-native
+# backlog-of-record store (`fleet/backlog/` — embedded PGlite data dir; see
+# packages/mosaic/src/commands/fleet-backlog.ts). Without these, an update
+# wipes the operator's fleet AND their backlog. Glob entries are honored by
+# both the rsync path (`--exclude`) and the glob-aware cp fallback below.
+PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials" "fleet/*.yaml" "fleet/agents" "fleet/run" "fleet/backlog")
 
 # Framework-owned contract files: re-copied from defaults/ on every upgrade (the
 # user must not edit them; a divergent copy is backed up once before overwrite).

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.42",
+  "version": "0.0.45",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",
@@ -29,6 +29,7 @@
   "dependencies": {
     "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
+    "@mosaicstack/db": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/log": "workspace:*",
     "@mosaicstack/macp": "workspace:*",

packages/mosaic/src/commands/fleet-backlog.ts

@@ -0,0 +1,285 @@
+/**
+ * `mosaic fleet backlog <sub> --json` — Mosaic-native backlog of record.
+ *
+ * Mosaic OWNS this backlog end-to-end on its existing Postgres storage layer
+ * (`@mosaicstack/db`). It REPLACES the former Hermes adapter — there is NO
+ * runtime dependency on Hermes.
+ *
+ * Storage tier (the existing storage-layer convention, no new engine):
+ *   - default: embedded PGlite at <mosaicHome>/fleet/backlog (real Postgres
+ *     semantics, persisted on disk so the operator's backlog survives reboots
+ *     and `mosaic update` — see install.sh PRESERVE_PATHS).
+ *   - DATABASE_URL set: full server Postgres — same code, no change.
+ *
+ * Migrations run on first use so the `backlog` table always exists.
+ */
+
+import { mkdir } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import type { Command } from 'commander';
+import {
+  BacklogService,
+  DEFAULT_CLAIM_TTL_SECONDS,
+  type BacklogCard,
+  type DbHandle,
+} from '@mosaicstack/db';
+
+function defaultMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+}
+
+/** Resolve where the embedded PGlite backlog store lives (default tier). */
+export function defaultBacklogDataDir(mosaicHome = defaultMosaicHome()): string {
+  return join(mosaicHome, 'fleet', 'backlog');
+}
+
+/**
+ * Open a db handle for the backlog and ensure the schema exists.
+ *
+ * Tier detection mirrors the storage layer: DATABASE_URL => server Postgres
+ * (migrations applied via runMigrations); otherwise embedded PGlite at the
+ * fleet/backlog data dir (migrations applied via runPgliteMigrations).
+ */
+async function openBacklogDb(mosaicHome: string): Promise<DbHandle> {
+  const { createDb, createPgliteDb, runMigrations, runPgliteMigrations } =
+    await import('@mosaicstack/db');
+  const url = process.env['DATABASE_URL'];
+  if (url) {
+    await runMigrations(url);
+    return createDb(url);
+  }
+  const dataDir = process.env['PGLITE_DATA_DIR'] ?? defaultBacklogDataDir(mosaicHome);
+  // PGlite writes a file-backed store to dataDir but does not create missing
+  // parent directories (e.g. <mosaicHome>/fleet). Create them first. Skip for
+  // the in-memory pseudo-paths so a memory:// store never touches the fs.
+  if (!dataDir.startsWith('memory://') && dataDir !== ':memory:') {
+    await mkdir(dataDir, { recursive: true });
+  }
+  const handle = createPgliteDb(dataDir);
+  await runPgliteMigrations(handle);
+  return handle;
+}
+
+function parseDependsOn(value?: string): string[] {
+  if (!value) return [];
+  return value
+    .split(',')
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+function parseAcceptance(value?: string): unknown {
+  if (!value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    // Fall back to a list of newline/semicolon-separated criteria.
+    return value
+      .split(/[\n;]/)
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0);
+  }
+}
+
+function printCard(card: BacklogCard | null, json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(card));
+    return;
+  }
+  if (!card) {
+    console.log('(none)');
+    return;
+  }
+  const deps = card.dependsOn.length ? card.dependsOn.join(',') : '-';
+  console.log(
+    `${card.id}\t[${card.status}]\tp=${card.priority}\tphase=${card.phase ?? '-'}\tdeps=${deps}\t${card.title}`,
+  );
+}
+
+function printCards(cards: BacklogCard[], json?: boolean): void {
+  if (json) {
+    console.log(JSON.stringify(cards));
+    return;
+  }
+  if (cards.length === 0) {
+    console.log('(no cards)');
+    return;
+  }
+  for (const card of cards) printCard(card, false);
+}
+
+/**
+ * Register `backlog` under an existing `fleet` command.
+ * `mosaicHomeFor` resolves the active --mosaic-home (parent flag) at call time.
+ */
+export function registerFleetBacklogCommand(
+  fleetCmd: Command,
+  mosaicHomeFor: () => string,
+): Command {
+  const backlogCmd = fleetCmd
+    .command('backlog')
+    .description('Mosaic-native backlog of record (atomic claim + TTL, deps DAG)');
+
+  const withSvc = async <T>(fn: (svc: BacklogService) => Promise<T>): Promise<T> => {
+    const handle = await openBacklogDb(mosaicHomeFor());
+    try {
+      return await fn(new BacklogService(handle.db));
+    } finally {
+      await handle.close();
+    }
+  };
+
+  backlogCmd
+    .command('create')
+    .description('Create a backlog card (idempotency_key dedups)')
+    .requiredOption('--id <id>', 'Stable card id')
+    .requiredOption('--title <title>', 'Card title')
+    .option('--body <body>', 'Card body / description')
+    .option('--phase <phase>', 'Board/phase grouping')
+    .option('--priority <n>', 'Priority (higher = sooner)', (v) => parseInt(v, 10), 0)
+    .option('--depends-on <ids>', 'Comma-separated dependency card ids')
+    .option('--acceptance <json>', 'Acceptance criteria (JSON or ;/newline list)')
+    .option('--idempotency-key <key>', 'Dedup key; repeat returns the existing card')
+    .option('--json', 'Print JSON')
+    .action(
+      async (opts: {
+        id: string;
+        title: string;
+        body?: string;
+        phase?: string;
+        priority: number;
+        dependsOn?: string;
+        acceptance?: string;
+        idempotencyKey?: string;
+        json?: boolean;
+      }) => {
+        const card = await withSvc((svc) =>
+          svc.create({
+            id: opts.id,
+            title: opts.title,
+            body: opts.body ?? null,
+            phase: opts.phase ?? null,
+            priority: opts.priority,
+            dependsOn: parseDependsOn(opts.dependsOn),
+            acceptance: parseAcceptance(opts.acceptance),
+            idempotencyKey: opts.idempotencyKey ?? null,
+          }),
+        );
+        printCard(card, opts.json);
+      },
+    );
+
+  backlogCmd
+    .command('list')
+    .description('List cards (filters: --status, --phase, --ready-only)')
+    .option('--status <status>', 'Filter by status: ready|claimed|blocked|done')
+    .option('--phase <phase>', 'Filter by phase')
+    .option('--ready-only', 'Only cards that are ready AND have all deps done')
+    .option('--json', 'Print JSON')
+    .action(
+      async (opts: {
+        status?: BacklogCard['status'];
+        phase?: string;
+        readyOnly?: boolean;
+        json?: boolean;
+      }) => {
+        const cards = await withSvc((svc) =>
+          svc.list({
+            ...(opts.status ? { status: opts.status } : {}),
+            ...(opts.phase ? { phase: opts.phase } : {}),
+            ...(opts.readyOnly ? { readyOnly: true } : {}),
+          }),
+        );
+        printCards(cards, opts.json);
+      },
+    );
+
+  backlogCmd
+    .command('claim')
+    .description('Atomically claim the highest-priority ready card (FOR UPDATE SKIP LOCKED)')
+    .requiredOption('--owner <owner>', 'Claim owner (worker/agent id)')
+    .option(
+      '--ttl <sec>',
+      'Claim TTL in seconds',
+      (v) => parseInt(v, 10),
+      DEFAULT_CLAIM_TTL_SECONDS,
+    )
+    .option('--id <id>', 'Claim a specific card by id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { owner: string; ttl: number; id?: string; json?: boolean }) => {
+      const card = await withSvc((svc) =>
+        svc.claim({ owner: opts.owner, ttlSeconds: opts.ttl, ...(opts.id ? { id: opts.id } : {}) }),
+      );
+      printCard(card, opts.json);
+      if (!card && !opts.json) process.exitCode = 0;
+    });
+
+  backlogCmd
+    .command('reclaim')
+    .description('Release expired claims back to ready (or a specific --id)')
+    .option('--id <id>', 'Release a specific card regardless of expiry')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id?: string; json?: boolean }) => {
+      const result = await withSvc((svc) => svc.reclaim(opts.id ? { id: opts.id } : {}));
+      if (opts.json) {
+        console.log(JSON.stringify(result));
+      } else if (result.reclaimed.length === 0) {
+        console.log('(nothing to reclaim)');
+      } else {
+        console.log(`reclaimed: ${result.reclaimed.join(', ')}`);
+      }
+    });
+
+  backlogCmd
+    .command('link')
+    .description('Add a depends_on edge (--from depends on --to)')
+    .requiredOption('--from <id>', 'Card that gains the dependency')
+    .requiredOption('--to <id>', 'Card it now depends on')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { from: string; to: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.link(opts.from, opts.to));
+      printCard(card, opts.json);
+    });
+
+  backlogCmd
+    .command('stats')
+    .description('Counts by status, oldest-ready age, expired-claim count')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { json?: boolean }) => {
+      const stats = await withSvc((svc) => svc.stats());
+      if (opts.json) {
+        console.log(JSON.stringify(stats));
+        return;
+      }
+      console.log(`total: ${stats.total}`);
+      console.log(
+        `ready=${stats.counts.ready} claimed=${stats.counts.claimed} ` +
+          `blocked=${stats.counts.blocked} done=${stats.counts.done}`,
+      );
+      console.log(`oldest-ready-age: ${stats.oldestReadyAgeSeconds ?? '-'}s`);
+      console.log(`expired-claims: ${stats.expiredClaimCount}`);
+    });
+
+  backlogCmd
+    .command('block')
+    .description('Mark a card blocked')
+    .requiredOption('--id <id>', 'Card id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.block(opts.id));
+      printCard(card, opts.json);
+    });
+
+  backlogCmd
+    .command('complete')
+    .description('Mark a card done')
+    .requiredOption('--id <id>', 'Card id')
+    .option('--json', 'Print JSON')
+    .action(async (opts: { id: string; json?: boolean }) => {
+      const card = await withSvc((svc) => svc.complete(opts.id));
+      printCard(card, opts.json);
+    });
+
+  return backlogCmd;
+}

packages/mosaic/src/commands/fleet-north-star.spec.ts

@@ -0,0 +1,199 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, it, vi } from 'vitest';
+import {
+  parseNorthStar,
+  renderNorthStarMarkdown,
+  resolveNorthStarPaths,
+  type NorthStar,
+} from './fleet.js';
+
+// Repo root resolved from this spec file: packages/mosaic/src/commands → up 4.
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+const yamlPath = join(repoRoot, 'docs', 'fleet', 'NORTH_STAR.yaml');
+
+async function loadYamlText(): Promise<string> {
+  return readFile(yamlPath, 'utf8');
+}
+
+async function loadParsed(): Promise<NorthStar> {
+  return parseNorthStar(await loadYamlText());
+}
+
+describe('NORTH_STAR.yaml', () => {
+  it('parses to a typed object with the required top-level keys', async () => {
+    const ns = await loadParsed();
+    expect(ns.version).toBeTypeOf('number');
+    expect(ns.mission).toContain('self-driving Mosaic delivery fleet');
+    expect(ns.substrate.note).toBeTruthy();
+    expect(ns.standing_objectives.length).toBeGreaterThan(0);
+    expect(ns.success_criteria.length).toBeGreaterThan(0);
+    expect(ns.workstreams.length).toBeGreaterThan(0);
+    expect(ns.goals.length).toBeGreaterThan(0);
+    expect(ns.assumptions.length).toBeGreaterThan(0);
+    expect(ns.spend.advisory).toBe(true);
+  });
+
+  it('names the native Postgres storage layer and declares no Hermes runtime dependency', async () => {
+    const rawText = await loadYamlText();
+    const lower = rawText.toLowerCase();
+    expect(rawText).toContain('@mosaicstack/db');
+    expect(lower).toContain('postgres');
+    expect(lower).toContain('pglite');
+    // The doctrine explicitly disowns Hermes ("NOT Hermes"); the only mentions
+    // are negations. Assert there is no Hermes RUNTIME dependency: no hermes
+    // CLI/kanban invocation and no ~/.hermes storage reference.
+    expect(lower).not.toContain('hermes kanban');
+    expect(lower).not.toContain('~/.hermes');
+    expect(lower).not.toContain('hermes mcp');
+  });
+
+  it('declares all NS-1..NS-8 standing objectives', async () => {
+    const ns = await loadParsed();
+    const ids = ns.standing_objectives.map((o) => o.id);
+    for (let n = 1; n <= 8; n += 1) {
+      expect(ids).toContain(`NS-${n}`);
+    }
+  });
+
+  it('declares all AC-NS-1..AC-NS-5 success criteria', async () => {
+    const ns = await loadParsed();
+    const ids = ns.success_criteria.map((c) => c.id);
+    for (let n = 1; n <= 5; n += 1) {
+      expect(ids).toContain(`AC-NS-${n}`);
+    }
+  });
+
+  it('seeds the expected backlog goal ids', async () => {
+    const ns = await loadParsed();
+    const ids = ns.goals.map((g) => g.id);
+    expect(ids).toEqual(
+      expect.arrayContaining(['A1', 'A2', 'A3a', 'A3b', 'A4', 'B1', 'B2', 'B3a', 'B3b', 'G1']),
+    );
+  });
+
+  it('has a coherent depends_on DAG (every dependency references a known goal)', async () => {
+    const ns = await loadParsed();
+    const ids = new Set(ns.goals.map((g) => g.id));
+    for (const goal of ns.goals) {
+      for (const dep of goal.depends_on) {
+        expect(ids.has(dep)).toBe(true);
+      }
+      // No goal may depend on itself.
+      expect(goal.depends_on).not.toContain(goal.id);
+    }
+    // A1 is the root: no dependencies.
+    const a1 = ns.goals.find((g) => g.id === 'A1');
+    expect(a1?.depends_on).toEqual([]);
+  });
+
+  it('marks spend as advisory with a degrade-to-TTL note', async () => {
+    const ns = await loadParsed();
+    expect(ns.spend.advisory).toBe(true);
+    expect(ns.spend.note.toLowerCase()).toContain('ttl');
+  });
+});
+
+describe('renderNorthStarMarkdown', () => {
+  it('is a pure deterministic projection (round-trip stable)', async () => {
+    const ns = await loadParsed();
+    const first = renderNorthStarMarkdown(ns);
+    const second = renderNorthStarMarkdown(ns);
+    expect(first).toBe(second);
+    // Re-parsing the same YAML and re-rendering yields identical bytes.
+    const reparsed = parseNorthStar(await loadYamlText());
+    expect(renderNorthStarMarkdown(reparsed)).toBe(first);
+  });
+
+  it('matches the committed NORTH_STAR.md projection (regenerate if this fails)', async () => {
+    const ns = await loadParsed();
+    const rendered = `${renderNorthStarMarkdown(ns)}\n`;
+    const committed = await readFile(join(repoRoot, 'docs', 'fleet', 'NORTH_STAR.md'), 'utf8');
+    expect(rendered).toBe(committed);
+  });
+
+  it('projects mission, objectives, criteria, goals, assumptions, and spend', async () => {
+    const ns = await loadParsed();
+    const md = renderNorthStarMarkdown(ns);
+    expect(md).toContain('# Mosaic Fleet — NORTH STAR');
+    expect(md).toContain('## Mission');
+    expect(md).toContain('## Standing objectives');
+    expect(md).toContain('**NS-1**');
+    expect(md).toContain('**AC-NS-5**');
+    expect(md).toContain('## Goals (backlog projection)');
+    // Tables are column-padded (prettier-style); match the row id, not exact spacing.
+    expect(md).toMatch(/\| A1\s+\|/);
+    expect(md).toContain('## Assumptions (vetoable)');
+    expect(md).toContain('**advisory:** true');
+    // The banner disowns Hermes; the projection carries no Hermes runtime hook.
+    expect(md.toLowerCase()).not.toContain('hermes kanban');
+    expect(md.toLowerCase()).not.toContain('~/.hermes');
+  });
+
+  it('does no network or CLI work (pure functions; only the writer touches IO)', () => {
+    // parseNorthStar + renderNorthStarMarkdown take strings and return strings.
+    // Guard against accidental IO by asserting fetch/spawn are never invoked.
+    const fetchSpy = vi.spyOn(globalThis, 'fetch' as never).mockImplementation((() => {
+      throw new Error('network access is forbidden in the NORTH_STAR generator');
+    }) as never);
+    try {
+      const yaml = [
+        'version: 1',
+        'mission: m',
+        'substrate:',
+        '  note: n',
+        'standing_objectives:',
+        '  - { id: NS-1, text: t }',
+        'success_criteria:',
+        '  - { id: AC-NS-1, text: t }',
+        'workstreams:',
+        '  - { id: A, title: t }',
+        'goals:',
+        '  - { id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }',
+        'assumptions:',
+        '  - { id: ASM-1, vetoable: true, text: t }',
+        'spend:',
+        '  advisory: true',
+        '  note: TTL',
+        '',
+      ].join('\n');
+      const ns = parseNorthStar(yaml);
+      const md = renderNorthStarMarkdown(ns);
+      expect(md).toContain('# Mosaic Fleet — NORTH STAR');
+      expect(fetchSpy).not.toHaveBeenCalled();
+    } finally {
+      fetchSpy.mockRestore();
+    }
+  });
+});
+
+describe('parseNorthStar validation', () => {
+  it('throws on a missing required key', () => {
+    expect(() => parseNorthStar('version: 1\n')).toThrow();
+  });
+
+  it('throws when spend.advisory is not a boolean', () => {
+    const yaml = [
+      'version: 1',
+      'mission: m',
+      'substrate: { note: n }',
+      'standing_objectives: [{ id: NS-1, text: t }]',
+      'success_criteria: [{ id: AC-NS-1, text: t }]',
+      'workstreams: [{ id: A, title: t }]',
+      'goals: [{ id: A1, title: t, phase: 1, priority: must-have, depends_on: [] }]',
+      'assumptions: [{ id: ASM-1, vetoable: true, text: t }]',
+      'spend: { advisory: maybe, note: TTL }',
+      '',
+    ].join('\n');
+    expect(() => parseNorthStar(yaml)).toThrow(/spend\.advisory/);
+  });
+});
+
+describe('resolveNorthStarPaths', () => {
+  it('resolves YAML + Markdown under docs/fleet from a given repo root', () => {
+    const paths = resolveNorthStarPaths('/repo');
+    expect(paths.yamlPath).toBe('/repo/docs/fleet/NORTH_STAR.yaml');
+    expect(paths.markdownPath).toBe('/repo/docs/fleet/NORTH_STAR.md');
+  });
+});

packages/mosaic/src/commands/fleet.spec.ts

@@ -27,7 +27,6 @@ import {
   enableFleetUnits,
   FLEET_PROFILES,
   HEARTBEAT_IDLE_THRESHOLD_SECONDS,
-  HEARTBEAT_STUCK_THRESHOLD_SECONDS,
   generateAgentEnv,
   getDefaultOperatorSourceLabel,
   getDefaultTenantAndHost,
@@ -48,7 +47,6 @@ import {
   resolvePresetFilename,
   RUNTIME_ACCEPTABLE_COMMANDS,
   serializeRosterToYaml,
-  stuckThresholdSeconds,
   VERIFY_DEFAULT_TIMEOUT_MS,
   VERIFY_POLL_INTERVAL_MS,
   type AgentPsRow,
@@ -80,6 +78,7 @@ describe('registerFleetCommand', () => {
     expect(fleet).toBeDefined();
     expect(fleet!.commands.map((command) => command.name()).sort()).toEqual([
       'add',
+      'backlog',
       'init',
       'install',
       'install-systemd',
@@ -93,6 +92,24 @@ describe('registerFleetCommand', () => {
     ]);
   });
 
+  it('registers the backlog subcommand with its operations', () => {
+    const program = buildProgram();
+    const fleet = program.commands.find((command) => command.name() === 'fleet');
+    const backlog = fleet!.commands.find((command) => command.name() === 'backlog');
+
+    expect(backlog).toBeDefined();
+    expect(backlog!.commands.map((command) => command.name()).sort()).toEqual([
+      'block',
+      'claim',
+      'complete',
+      'create',
+      'link',
+      'list',
+      'reclaim',
+      'stats',
+    ]);
+  });
+
   it('adds fleet-backed agent subcommands without removing existing options', () => {
     const program = buildProgram();
     const agent = program.commands.find((command) => command.name() === 'agent');
@@ -855,7 +872,7 @@ describe('fleet ps — command construction', () => {
       '-t',
       '=canary-pi:0.0',
       '-F',
-      '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}',
+      '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}',
     ]);
   });
 
@@ -940,42 +957,33 @@ describe('fleet ps — heartbeat parsing', () => {
 
 describe('fleet ps — readiness thresholds', () => {
   const savedIdle = process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-  const savedStuck = process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD;
 
   afterEach(() => {
     if (savedIdle === undefined) delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
     else process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = savedIdle;
-    if (savedStuck === undefined) delete process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD;
-    else process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD = savedStuck;
   });
 
-  it('uses default readiness thresholds when env is unset', () => {
+  it('uses the default activity threshold when env is unset', () => {
     delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-    delete process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD;
 
     expect(idleThresholdSeconds()).toBe(HEARTBEAT_IDLE_THRESHOLD_SECONDS);
-    expect(stuckThresholdSeconds()).toBe(HEARTBEAT_STUCK_THRESHOLD_SECONDS);
   });
 
-  it('honors positive integer readiness thresholds from env', () => {
+  it('honors a positive integer activity threshold from env', () => {
     process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '120';
-    process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD = '480';
 
     expect(idleThresholdSeconds()).toBe(120);
-    expect(stuckThresholdSeconds()).toBe(480);
   });
 
-  it('falls back to defaults for invalid readiness thresholds', () => {
+  it('falls back to the default for invalid activity thresholds', () => {
     process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '0';
-    process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD = 'not-a-number';
 
     expect(idleThresholdSeconds()).toBe(HEARTBEAT_IDLE_THRESHOLD_SECONDS);
-    expect(stuckThresholdSeconds()).toBe(HEARTBEAT_STUCK_THRESHOLD_SECONDS);
   });
 });
 
 describe('fleet ps — readiness classification', () => {
-  const thresholds = { idleThresholdSeconds: 300, stuckThresholdSeconds: 900 };
+  const thresholds = { idleThresholdSeconds: 300 };
 
   it('reports dead when the pane is not alive', () => {
     expect(
@@ -1004,7 +1012,7 @@ describe('fleet ps — readiness classification', () => {
     ).toBe('stale');
   });
 
-  it('reports working when heartbeat status is busy, even past stuck threshold', () => {
+  it('reports working when heartbeat status is busy, even after the activity threshold', () => {
     expect(
       classifyReadiness(
         { paneAlive: true, hbHealth: 'healthy', hbStatus: 'busy', idleSeconds: 2_000 },
@@ -1013,7 +1021,7 @@ describe('fleet ps — readiness classification', () => {
     ).toBe('working');
   });
 
-  it('reports working when pane idle seconds are unavailable', () => {
+  it('reports working when pane idle seconds are null', () => {
     expect(
       classifyReadiness(
         { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: null },
@@ -1022,25 +1030,31 @@ describe('fleet ps — readiness classification', () => {
     ).toBe('working');
   });
 
-  it('reports stuck at the stuck threshold boundary', () => {
+  it('reports working when pane idle seconds are undefined', () => {
     expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 900 },
-        thresholds,
-      ),
-    ).toBe('stuck');
+      classifyReadiness({ paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok' }, thresholds),
+    ).toBe('working');
   });
 
-  it('reports idle at the idle threshold boundary', () => {
+  it('reports working when pane idle seconds are non-finite', () => {
+    expect(
+      classifyReadiness(
+        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: Number.NaN },
+        thresholds,
+      ),
+    ).toBe('working');
+  });
+
+  it('reports available at the activity threshold boundary', () => {
     expect(
       classifyReadiness(
         { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 300 },
         thresholds,
       ),
-    ).toBe('idle');
+    ).toBe('available');
   });
 
-  it('reports working below the idle threshold', () => {
+  it('reports working below the activity threshold', () => {
     expect(
       classifyReadiness(
         { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 299 },
@@ -1049,13 +1063,14 @@ describe('fleet ps — readiness classification', () => {
     ).toBe('working');
   });
 
-  it('checks stuck before idle when thresholds are inverted', () => {
-    expect(
-      classifyReadiness(
-        { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 350 },
-        { idleThresholdSeconds: 900, stuckThresholdSeconds: 300 },
-      ),
-    ).toBe('stuck');
+  it('reports very long idle as available, not stuck', () => {
+    const readiness = classifyReadiness(
+      { paneAlive: true, hbHealth: 'healthy', hbStatus: 'ok', idleSeconds: 100_000 },
+      thresholds,
+    );
+
+    expect(readiness).toBe('available');
+    expect(readiness).not.toBe('stuck');
   });
 });
 
@@ -1079,9 +1094,11 @@ describe('fleet ps — systemd show parsing', () => {
 describe('fleet ps — tmux list-panes parsing', () => {
   const NOW_MS = 1_700_000_000_000;
 
-  it('parses alive pane with pid, command, and idle time', () => {
-    const activityEpoch = Math.floor((NOW_MS - 30_000) / 1000); // 30s ago
-    const output = `12345 claude 0 ${activityEpoch}\n`;
+  it('uses pane_activity when present', () => {
+    const paneActivityEpoch = Math.floor((NOW_MS - 30_000) / 1000); // 30s ago
+    const windowActivityEpoch = Math.floor((NOW_MS - 60_000) / 1000); // 60s ago
+    const sessionActivityEpoch = Math.floor((NOW_MS - 90_000) / 1000); // 90s ago
+    const output = `12345 claude 0 ${paneActivityEpoch} ${windowActivityEpoch} ${sessionActivityEpoch}\n`;
     const result = parseTmuxListPanes(output, NOW_MS);
     expect(result.pid).toBe(12345);
     expect(result.command).toBe('claude');
@@ -1089,8 +1106,45 @@ describe('fleet ps — tmux list-panes parsing', () => {
     expect(result.idleSeconds).toBe(30);
   });
 
+  it('uses window_activity when pane_activity is empty', () => {
+    const windowActivityEpoch = Math.floor((NOW_MS - 45_000) / 1000); // 45s ago
+    const sessionActivityEpoch = Math.floor((NOW_MS - 90_000) / 1000); // 90s ago
+    const output = `12345 node 0  ${windowActivityEpoch} ${sessionActivityEpoch}\n`;
+    expect(output).toContain('0  '); // empty pane_activity preserves index alignment
+    const result = parseTmuxListPanes(output, NOW_MS);
+    expect(result.pid).toBe(12345);
+    expect(result.command).toBe('node');
+    expect(result.dead).toBe(false);
+    expect(result.idleSeconds).toBe(45);
+  });
+
+  it('uses session_activity when pane_activity and window_activity are empty', () => {
+    const sessionActivityEpoch = Math.floor((NOW_MS - 75_000) / 1000); // 75s ago
+    const output = `12345 node 0   ${sessionActivityEpoch}\n`;
+    const result = parseTmuxListPanes(output, NOW_MS);
+    expect(result.idleSeconds).toBe(75);
+  });
+
+  it('reports null idleSeconds when all activity sources are empty', () => {
+    const output = '12345 node 0   \n';
+    const result = parseTmuxListPanes(output, NOW_MS);
+    expect(result.idleSeconds).toBeNull();
+  });
+
+  it('computes exact idle seconds from now minus epoch seconds', () => {
+    const activityEpoch = 1_699_999_877;
+    const result = parseTmuxListPanes(`12345 claude 0 ${activityEpoch} 0 0\n`, NOW_MS);
+    expect(result.idleSeconds).toBe(123);
+  });
+
+  it('clamps future activity epochs to 0 idle seconds', () => {
+    const futureActivityEpoch = Math.floor((NOW_MS + 30_000) / 1000);
+    const result = parseTmuxListPanes(`12345 claude 0 ${futureActivityEpoch} 0 0\n`, NOW_MS);
+    expect(result.idleSeconds).toBe(0);
+  });
+
   it('reports dead pane when pane_dead=1', () => {
-    const output = `0 bash 1 0\n`;
+    const output = `0 bash 1 0 0 0\n`;
     const result = parseTmuxListPanes(output, NOW_MS);
     expect(result.dead).toBe(true);
   });
@@ -1515,7 +1569,7 @@ describe('fleet ps — command sequences issued', () => {
 });
 
 describe('fleet ps — readiness table output', () => {
-  it('renders readiness in HB column and flags idle/stuck rows', async () => {
+  it('renders available in HB column without idle/stuck alarm flags', async () => {
     const home = await mkdtemp(join(tmpdir(), 'mosaic-fleet-'));
     const rosterPath = join(home, 'fleet', 'roster.yaml');
     const runDir = join(home, 'fleet', 'run');
@@ -1526,36 +1580,34 @@ describe('fleet ps — readiness table output', () => {
         'version: 1',
         'transport: tmux',
         'agents:',
-        '  - name: idle-agent',
+        '  - name: working-agent',
         '    runtime: pi',
-        '  - name: stuck-agent',
+        '  - name: available-agent',
         '    runtime: pi',
       ].join('\n'),
     );
 
     const nowMs = 1_700_000_000_000;
-    const idleActivityEpoch = Math.floor((nowMs - 10_000) / 1000);
-    const stuckActivityEpoch = Math.floor((nowMs - 40_000) / 1000);
+    const workingActivityEpoch = Math.floor((nowMs - 2_000) / 1000);
+    const availableActivityEpoch = Math.floor((nowMs - 40_000) / 1000);
     const hbTs = new Date(nowMs - 1_000).toISOString();
-    await writeFile(join(runDir, 'idle-agent.hb'), `ts=${hbTs}\npid=111\nstatus=ok\n`);
-    await writeFile(join(runDir, 'stuck-agent.hb'), `ts=${hbTs}\npid=222\nstatus=ok\n`);
+    await writeFile(join(runDir, 'working-agent.hb'), `ts=${hbTs}\npid=111\nstatus=ok\n`);
+    await writeFile(join(runDir, 'available-agent.hb'), `ts=${hbTs}\npid=222\nstatus=ok\n`);
 
     const savedIdle = process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
-    const savedStuck = process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD;
     process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = '5';
-    process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD = '30';
 
     const dateNow = vi.spyOn(Date, 'now').mockReturnValue(nowMs);
     const runner: CommandRunner = async (command, args) => {
       const full = [command, ...args].join(' ');
       if (full.includes('list-sessions')) {
-        return { stdout: 'idle-agent\nstuck-agent\n', stderr: '', exitCode: 0 };
+        return { stdout: 'working-agent\navailable-agent\n', stderr: '', exitCode: 0 };
       }
-      if (full.includes('=idle-agent:0.0')) {
-        return { stdout: `111 pi 0 ${idleActivityEpoch}\n`, stderr: '', exitCode: 0 };
+      if (full.includes('=working-agent:0.0')) {
+        return { stdout: `111 pi 0 ${workingActivityEpoch}\n`, stderr: '', exitCode: 0 };
       }
-      if (full.includes('=stuck-agent:0.0')) {
-        return { stdout: `222 pi 0 ${stuckActivityEpoch}\n`, stderr: '', exitCode: 0 };
+      if (full.includes('=available-agent:0.0')) {
+        return { stdout: `222 pi 0 ${availableActivityEpoch}\n`, stderr: '', exitCode: 0 };
       }
       if (full.includes('systemctl') && full.includes('show')) {
         return {
@@ -1584,19 +1636,17 @@ describe('fleet ps — readiness table output', () => {
       dateNow.mockRestore();
       if (savedIdle === undefined) delete process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD;
       else process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD = savedIdle;
-      if (savedStuck === undefined) delete process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD;
-      else process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD = savedStuck;
       await rm(home, { recursive: true, force: true });
     }
 
-    const idleLine = lines.find((line) => line.includes('idle-agent'));
-    const stuckLine = lines.find((line) => line.includes('stuck-agent'));
-    expect(idleLine).toBeDefined();
-    expect(idleLine).toContain('1s/idle');
-    expect(idleLine).toMatch(/\bIDLE\b/);
-    expect(stuckLine).toBeDefined();
-    expect(stuckLine).toContain('1s/stuck');
-    expect(stuckLine).toMatch(/\bSTUCK\b/);
+    const workingLine = lines.find((line) => line.includes('working-agent'));
+    const availableLine = lines.find((line) => line.includes('available-agent'));
+    expect(workingLine).toBeDefined();
+    expect(workingLine).toContain('1s/working');
+    expect(availableLine).toBeDefined();
+    expect(availableLine).toContain('1s/available');
+    expect(availableLine).not.toMatch(/\bIDLE\b/);
+    expect(availableLine).not.toMatch(/\bSTUCK\b/);
   });
 });
 

packages/mosaic/src/commands/fleet.ts

@@ -8,6 +8,7 @@ import * as readline from 'node:readline';
 import type { Command } from 'commander';
 import YAML from 'yaml';
 import { resolveCommsBlock } from '../fleet/comms-onboarding.js';
+import { registerFleetBacklogCommand } from './fleet-backlog.js';
 
 /**
  * A function that spawns a command with inherited stdio (TTY passthrough).
@@ -197,6 +198,292 @@ export function getRosterAgent(roster: FleetRoster, name: string): FleetAgent {
   return agent;
 }
 
+// ---------------------------------------------------------------------------
+// NORTH_STAR — machine-readable fleet planning source + Markdown projection
+//
+// docs/fleet/NORTH_STAR.yaml is the single source of truth. The Markdown file
+// (docs/fleet/NORTH_STAR.md) is a deterministic, pure projection of the YAML —
+// no network, no CLI, no clock. Edit the YAML, regenerate the .md.
+// ---------------------------------------------------------------------------
+
+export interface NorthStarIdText {
+  id: string;
+  text: string;
+}
+
+export interface NorthStarWorkstream {
+  id: string;
+  title: string;
+}
+
+export interface NorthStarGoal {
+  id: string;
+  title: string;
+  phase: number;
+  priority: string;
+  depends_on: string[];
+}
+
+export interface NorthStarAssumption {
+  id: string;
+  vetoable: boolean;
+  text: string;
+}
+
+export interface NorthStarSpend {
+  advisory: boolean;
+  note: string;
+}
+
+export interface NorthStar {
+  version: number;
+  mission: string;
+  substrate: { note: string };
+  standing_objectives: NorthStarIdText[];
+  success_criteria: NorthStarIdText[];
+  workstreams: NorthStarWorkstream[];
+  goals: NorthStarGoal[];
+  assumptions: NorthStarAssumption[];
+  spend: NorthStarSpend;
+}
+
+/**
+ * Parse + validate the NORTH_STAR YAML text into a typed NorthStar object.
+ * Pure: no IO, no network. Throws a descriptive error when a required key is
+ * missing or malformed so the generator/tests fail loudly rather than emit a
+ * partial projection.
+ */
+export function parseNorthStar(rawText: string): NorthStar {
+  const parsed = YAML.parse(rawText) as Record<string, unknown> | null;
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error('NORTH_STAR.yaml did not parse to a mapping.');
+  }
+
+  const requireString = (value: unknown, key: string): string => {
+    if (typeof value !== 'string' || value.trim() === '') {
+      throw new Error(`NORTH_STAR.yaml: "${key}" must be a non-empty string.`);
+    }
+    return value.trim();
+  };
+
+  const requireArray = (value: unknown, key: string): unknown[] => {
+    if (!Array.isArray(value) || value.length === 0) {
+      throw new Error(`NORTH_STAR.yaml: "${key}" must be a non-empty array.`);
+    }
+    return value;
+  };
+
+  const idText = (value: unknown, key: string, index: number): NorthStarIdText => {
+    const row = value as Record<string, unknown>;
+    return {
+      id: requireString(row?.id, `${key}[${index}].id`),
+      text: requireString(row?.text, `${key}[${index}].text`),
+    };
+  };
+
+  const version = parsed.version;
+  if (typeof version !== 'number') {
+    throw new Error('NORTH_STAR.yaml: "version" must be a number.');
+  }
+
+  const substrate = parsed.substrate as Record<string, unknown> | undefined;
+
+  const spendRaw = parsed.spend as Record<string, unknown> | undefined;
+  if (!spendRaw || typeof spendRaw.advisory !== 'boolean') {
+    throw new Error('NORTH_STAR.yaml: "spend.advisory" must be a boolean.');
+  }
+
+  return {
+    version,
+    mission: requireString(parsed.mission, 'mission'),
+    substrate: { note: requireString(substrate?.note, 'substrate.note') },
+    standing_objectives: requireArray(parsed.standing_objectives, 'standing_objectives').map(
+      (row, i) => idText(row, 'standing_objectives', i),
+    ),
+    success_criteria: requireArray(parsed.success_criteria, 'success_criteria').map((row, i) =>
+      idText(row, 'success_criteria', i),
+    ),
+    workstreams: requireArray(parsed.workstreams, 'workstreams').map((row, i) => {
+      const ws = row as Record<string, unknown>;
+      return {
+        id: requireString(ws?.id, `workstreams[${i}].id`),
+        title: requireString(ws?.title, `workstreams[${i}].title`),
+      };
+    }),
+    goals: requireArray(parsed.goals, 'goals').map((row, i) => {
+      const goal = row as Record<string, unknown>;
+      const dependsRaw = goal?.depends_on ?? [];
+      if (!Array.isArray(dependsRaw)) {
+        throw new Error(`NORTH_STAR.yaml: goals[${i}].depends_on must be an array.`);
+      }
+      const phase = goal?.phase;
+      if (typeof phase !== 'number') {
+        throw new Error(`NORTH_STAR.yaml: goals[${i}].phase must be a number.`);
+      }
+      return {
+        id: requireString(goal?.id, `goals[${i}].id`),
+        title: requireString(goal?.title, `goals[${i}].title`),
+        phase,
+        priority: requireString(goal?.priority, `goals[${i}].priority`),
+        depends_on: dependsRaw.map((dep, j) => requireString(dep, `goals[${i}].depends_on[${j}]`)),
+      };
+    }),
+    assumptions: requireArray(parsed.assumptions, 'assumptions').map((row, i) => {
+      const asm = row as Record<string, unknown>;
+      if (typeof asm?.vetoable !== 'boolean') {
+        throw new Error(`NORTH_STAR.yaml: assumptions[${i}].vetoable must be a boolean.`);
+      }
+      return {
+        id: requireString(asm?.id, `assumptions[${i}].id`),
+        vetoable: asm.vetoable,
+        text: requireString(asm?.text, `assumptions[${i}].text`),
+      };
+    }),
+    spend: {
+      advisory: spendRaw.advisory,
+      note: requireString(spendRaw?.note, 'spend.note'),
+    },
+  };
+}
+
+/**
+ * Render a GitHub-Flavored-Markdown table with prettier-compatible column
+ * alignment: each column is padded to the widest cell (minimum 3 for the
+ * `---` divider) so the generated bytes survive `prettier --check` unchanged.
+ * Pure; the row strings use the same single-code-unit dash/arrow glyphs that
+ * prettier's string-width counts as width 1.
+ */
+function renderMarkdownTable(headers: string[], rows: string[][]): string[] {
+  const widths = headers.map((header, col) =>
+    Math.max(3, header.length, ...rows.map((row) => row[col]?.length ?? 0)),
+  );
+  const pad = (cell: string, col: number): string => cell.padEnd(widths[col] ?? 0, ' ');
+  const formatRow = (cells: string[]): string =>
+    `| ${cells.map((cell, col) => pad(cell, col)).join(' | ')} |`;
+  const divider = `| ${widths.map((w) => '-'.repeat(w)).join(' | ')} |`;
+  return [formatRow(headers), divider, ...rows.map(formatRow)];
+}
+
+/**
+ * Deterministically project a parsed NorthStar into the Markdown doctrine doc.
+ * Pure function of its input — same input always yields byte-identical output,
+ * so the round-trip (YAML → render → write) is stable across runs. No clock, no
+ * network, no CLI. Layout follows the repo's existing doctrine-doc convention
+ * (heading, blockquote banner, then sections + tables, e.g. north-star.md /
+ * mission-control/BOARD.md).
+ */
+export function renderNorthStarMarkdown(ns: NorthStar): string {
+  const lines: string[] = [];
+
+  lines.push('# Mosaic Fleet — NORTH STAR');
+  lines.push('');
+  lines.push('> **Generated file — do not edit by hand.**');
+  lines.push(
+    '> Projected deterministically from [`NORTH_STAR.yaml`](./NORTH_STAR.yaml) by the pure',
+  );
+  lines.push('> generator in `packages/mosaic/src/commands/fleet.ts` (`renderNorthStarMarkdown`).');
+  lines.push('> Edit the YAML, then regenerate. Self-contained Mosaic — no Hermes dependency.');
+  lines.push('');
+
+  lines.push('## Mission');
+  lines.push('');
+  lines.push(ns.mission);
+  lines.push('');
+
+  lines.push('## Substrate');
+  lines.push('');
+  lines.push(ns.substrate.note);
+  lines.push('');
+
+  lines.push('## Standing objectives');
+  lines.push('');
+  for (const obj of ns.standing_objectives) {
+    lines.push(`- **${obj.id}** — ${obj.text}`);
+  }
+  lines.push('');
+
+  lines.push('## Success criteria');
+  lines.push('');
+  for (const ac of ns.success_criteria) {
+    lines.push(`- **${ac.id}** — ${ac.text}`);
+  }
+  lines.push('');
+
+  lines.push('## Workstreams');
+  lines.push('');
+  lines.push(
+    ...renderMarkdownTable(
+      ['id', 'title'],
+      ns.workstreams.map((ws) => [ws.id, ws.title]),
+    ),
+  );
+  lines.push('');
+
+  lines.push('## Goals (backlog projection)');
+  lines.push('');
+  lines.push(
+    ...renderMarkdownTable(
+      ['id', 'title', 'phase', 'priority', 'depends_on'],
+      ns.goals.map((goal) => [
+        goal.id,
+        goal.title,
+        String(goal.phase),
+        goal.priority,
+        goal.depends_on.length > 0 ? goal.depends_on.join(', ') : '—',
+      ]),
+    ),
+  );
+  lines.push('');
+
+  lines.push('## Assumptions (vetoable)');
+  lines.push('');
+  for (const asm of ns.assumptions) {
+    const veto = asm.vetoable ? 'vetoable' : 'fixed';
+    lines.push(`- **${asm.id}** (${veto}) — ${asm.text}`);
+  }
+  lines.push('');
+
+  lines.push('## Spend');
+  lines.push('');
+  lines.push(`- **advisory:** ${ns.spend.advisory ? 'true' : 'false'}`);
+  lines.push(`- ${ns.spend.note}`);
+
+  // No trailing blank line: the writer appends a single newline, yielding the
+  // one-newline EOF prettier expects (round-trip stays format:check-clean).
+  return lines.join('\n');
+}
+
+/**
+ * Resolve the repo's docs/fleet directory from this compiled module's location.
+ * fleet.ts lives at packages/mosaic/src/commands; docs/fleet sits at the repo
+ * root. Exposed so the generator + tests share one path resolution.
+ */
+export function resolveNorthStarPaths(repoRoot?: string): {
+  yamlPath: string;
+  markdownPath: string;
+} {
+  const root = repoRoot ?? resolve(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+  const dir = join(root, 'docs', 'fleet');
+  return {
+    yamlPath: join(dir, 'NORTH_STAR.yaml'),
+    markdownPath: join(dir, 'NORTH_STAR.md'),
+  };
+}
+
+/**
+ * Read NORTH_STAR.yaml, project it to Markdown, and write NORTH_STAR.md.
+ * The only IO in the NORTH_STAR pipeline; the parse + render steps it composes
+ * are pure. Returns the rendered Markdown so callers/tests can assert on it.
+ */
+export async function generateNorthStarMarkdown(repoRoot?: string): Promise<string> {
+  const { yamlPath, markdownPath } = resolveNorthStarPaths(repoRoot);
+  const rawText = await readFile(yamlPath, 'utf8');
+  const ns = parseNorthStar(rawText);
+  const markdown = renderNorthStarMarkdown(ns);
+  await writeFile(markdownPath, `${markdown}\n`, 'utf8');
+  return markdown;
+}
+
 export function generateAgentEnv(roster: FleetRoster, agent: FleetAgent): string {
   const workingDirectory = agent.workingDirectory ?? roster.defaults.workingDirectory;
   return [
@@ -395,7 +682,6 @@ export function buildAgentTailCommand(agentName: string, lines: number, socketNa
 
 export const HEARTBEAT_INTERVAL_MS = 15_000;
 export const HEARTBEAT_IDLE_THRESHOLD_SECONDS = 300;
-export const HEARTBEAT_STUCK_THRESHOLD_SECONDS = 900;
 
 /**
  * Heartbeat interval in ms, honoring MOSAIC_HEARTBEAT_INTERVAL (seconds) so the
@@ -407,20 +693,14 @@ export function heartbeatIntervalMs(): number {
   return Number.isFinite(sec) && sec > 0 ? sec * 1000 : HEARTBEAT_INTERVAL_MS;
 }
 
-/** Idle threshold in seconds, honoring MOSAIC_HEARTBEAT_IDLE_THRESHOLD. */
+/** Activity threshold in seconds, honoring MOSAIC_HEARTBEAT_IDLE_THRESHOLD. */
 export function idleThresholdSeconds(): number {
   const sec = Number.parseInt(process.env.MOSAIC_HEARTBEAT_IDLE_THRESHOLD ?? '', 10);
   return Number.isFinite(sec) && sec > 0 ? sec : HEARTBEAT_IDLE_THRESHOLD_SECONDS;
 }
-
-/** Stuck threshold in seconds, honoring MOSAIC_HEARTBEAT_STUCK_THRESHOLD. */
-export function stuckThresholdSeconds(): number {
-  const sec = Number.parseInt(process.env.MOSAIC_HEARTBEAT_STUCK_THRESHOLD ?? '', 10);
-  return Number.isFinite(sec) && sec > 0 ? sec : HEARTBEAT_STUCK_THRESHOLD_SECONDS;
-}
 export const HEARTBEAT_HEALTHY_MULTIPLIER = 3;
 
-export type ReadinessState = 'working' | 'idle' | 'stuck' | 'stale' | 'dead' | 'unknown';
+export type ReadinessState = 'working' | 'available' | 'stuck' | 'stale' | 'dead' | 'unknown';
 
 export interface ReadinessSignals {
   paneAlive: boolean;
@@ -431,7 +711,6 @@ export interface ReadinessSignals {
 
 export interface ReadinessThresholds {
   idleThresholdSeconds: number;
-  stuckThresholdSeconds: number;
 }
 
 /**
@@ -456,12 +735,8 @@ export function classifyReadiness(
     const idleThreshold = Number.isFinite(thresholds?.idleThresholdSeconds)
       ? Number(thresholds?.idleThresholdSeconds)
       : idleThresholdSeconds();
-    const stuckThreshold = Number.isFinite(thresholds?.stuckThresholdSeconds)
-      ? Number(thresholds?.stuckThresholdSeconds)
-      : stuckThresholdSeconds();
-
-    if (idleSeconds >= stuckThreshold) return 'stuck';
-    if (idleSeconds >= idleThreshold) return 'idle';
+    // Follow-up: stuck pending per-agent assignment awareness: assigned task + idle past threshold => stuck.
+    if (idleSeconds >= idleThreshold) return 'available';
     return 'working';
   } catch {
     return 'unknown';
@@ -524,7 +799,7 @@ export function buildSystemdShowCommand(agentName: string): string[] {
 
 /**
  * Returns the tmux list-panes command for an agent pane.
- * Format: `#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}`
+ * Format: `#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}`
  */
 export function buildTmuxListPanesCommand(agentName: string, socketName = ''): string[] {
   return [
@@ -534,7 +809,7 @@ export function buildTmuxListPanesCommand(agentName: string, socketName = ''): s
     '-t',
     `=${agentName}:0.0`,
     '-F',
-    '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}',
+    '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}',
   ];
 }
 
@@ -634,8 +909,8 @@ export function parseSystemdShow(output: string): {
 }
 
 /**
- * Parse the output of `tmux list-panes -F '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity}'`
- * pane_activity is a Unix epoch timestamp (seconds).
+ * Parse the output of `tmux list-panes -F '#{pane_pid} #{pane_current_command} #{pane_dead} #{pane_activity} #{window_activity} #{session_activity}'`
+ * Activity fields are Unix epoch timestamps (seconds), ordered most precise to coarsest.
  */
 export function parseTmuxListPanes(
   output: string,
@@ -645,16 +920,18 @@ export function parseTmuxListPanes(
   if (!line) {
     return { pid: null, command: null, dead: true, idleSeconds: null };
   }
-  // format: <pid> <command> <dead(0|1)> <activity_epoch>
+  // format: <pid> <command> <dead(0|1)> <pane_activity> <window_activity> <session_activity>
   const parts = line.split(' ');
   const pid = parts[0] ? (Number.isFinite(Number(parts[0])) ? Number(parts[0]) : null) : null;
   const command = parts[1] ?? null;
   const dead = parts[2] === '1';
-  const activityEpoch = parts[3] ? Number(parts[3]) : NaN;
-  const idleSeconds =
-    Number.isFinite(activityEpoch) && activityEpoch > 0
-      ? Math.floor((nowMs - activityEpoch * 1000) / 1000)
-      : null;
+  const activityEpoch = parts
+    .slice(3, 6)
+    .map((part) => (part ? Number(part) : NaN))
+    .find((epoch) => Number.isFinite(epoch) && epoch > 0);
+  const idleSeconds = activityEpoch
+    ? Math.max(0, Math.floor((nowMs - activityEpoch * 1000) / 1000))
+    : null;
   return { pid, command, dead, idleSeconds };
 }
 
@@ -1087,7 +1364,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       const rows: AgentPsRow[] = [];
       const readinessThresholds = {
         idleThresholdSeconds: idleThresholdSeconds(),
-        stuckThresholdSeconds: stuckThresholdSeconds(),
       };
 
       // Build the set of roster agent names for quick lookup when filtering socket sessions.
@@ -1262,8 +1538,6 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
         if (!row.managed) flags.push('UNMANAGED');
         if (row.driftFlag) flags.push('DRIFT');
         if (row.bootEnableWarning) flags.push('BOOT-ENABLE');
-        if (row.readiness === 'idle') flags.push('IDLE');
-        if (row.readiness === 'stuck') flags.push('STUCK');
 
         console.log(
           [
@@ -1427,6 +1701,11 @@ export function registerFleetCommand(program: Command, deps: FleetCommandDeps =
       console.log(`Removed ${name} from the fleet.`);
     });
 
+  // Mosaic-native backlog of record (card A4). Resolves the active --mosaic-home
+  // (parent flag) at call time so the embedded PGlite store lands under the same
+  // fleet/ directory as the roster and heartbeats.
+  registerFleetBacklogCommand(cmd, () => cmd.opts<{ mosaicHome: string }>().mosaicHome);
+
   return cmd;
 }
 

pnpm-lock.yaml

@@ -540,6 +540,9 @@ importers:
       '@mosaicstack/config':
         specifier: workspace:*
         version: link:../config
+      '@mosaicstack/db':
+        specifier: workspace:*
+        version: link:../db
       '@mosaicstack/forge':
         specifier: workspace:*
         version: link:../forge