feat(fleet): classify agent readiness in fleet ps (#649)

docs/scratchpads/h1-heartbeat-readiness.md

@@ -0,0 +1,66 @@
+# 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.