# H1 — heartbeat readiness detection

## Objective

Add runtime-agnostic readiness classification to `mosaic fleet ps` so an agent can be reported as working/idle/stuck/stale/dead/unknown instead of treating pane liveness as progress.

## Scope

- `packages/mosaic/src/commands/fleet.ts`
  - exported readiness state/types/default thresholds/helpers/classifier
  - `AgentPsRow.readiness` additive JSON field
  - table HB column and IDLE/STUCK flags
- `packages/mosaic/src/commands/fleet.spec.ts`
  - pure classifier branch/boundary coverage
  - threshold helper coverage
  - legitimate render/JSON assertion updates for new HB text

## Acceptance Criteria

- Branches covered: dead, unknown, stale, busy working, null-idle working, stuck boundary, idle boundary, working below idle.
- Threshold env helpers default to 300s/900s and honor positive integer env values.
- `fleet ps` rows populate `readiness` for roster and unmanaged socket sessions.
- Table HB text becomes `<age>s/<readiness>` when heartbeat age exists; remains `unknown` when absent.
- Flags include `IDLE`/`STUCK` for matching readiness.
- Local gates green: `pnpm typecheck`, `pnpm lint`, `pnpm format:check`, fleet vitest.
- Pre-push queue guard passes; PR opened off `origin/main`; no merge by worker.

## Constraints / Assumptions

- Source branch: `origin/main` @ `e3adc6a`.
- No scope creep beyond readiness detection.
- `docs/TASKS.md` and `docs/fleet/TASKS.md` are orchestrator-owned; worker will not modify them.
- PRD alignment source: `docs/fleet/PRD.md` Phase 2 observability; this is a refinement of heartbeat observability, preserving existing unknown/stale behavior.

## Plan

1. Install dependencies with requested PNPM environment.
2. Add readiness types/helpers/classifier near heartbeat constants.
3. Add `readiness` to `AgentPsRow` and populate both row paths.
4. Update table render and flags.
5. Add unit tests and update affected ps render/JSON assertions.
6. Run build precheck + required gates.
7. Run automated independent review, remediate findings.
8. Queue guard, push, open PR.

## Progress

- 2026-06-24: Branch created from `origin/main` @ `e3adc6a`.
- 2026-06-24: Implemented readiness thresholds/classifier, JSON row field, HB column label, and IDLE/STUCK flags.
- 2026-06-24: Added classifier branch/boundary tests, threshold helper tests, JSON shape assertions, and readiness table rendering assertions.

## 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, 171 tests.
- `pnpm --filter @mosaicstack/mosaic test` — pass, 39 files / 547 tests; `fleet.spec.ts` 171 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.