stack/docs/scratchpads/h1-heartbeat-readiness.md

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.