Document Phase 661 runtime telemetry completion for agentctl.

This records heartbeat/startup sidecar event contracts, ping handshake metadata semantics, and marks the corresponding roadmap runtime hardening tasks complete.

Co-authored-by: Cursor <[email protected]>

AGENTCTL.md

@@ -58,6 +58,7 @@ If `ping` fails with `ECONN_REFUSED`, verify the app was launched with `PEARCORD
 If `preflight` or `ping` returns `EMODULE_MISSING`, run `npm install` in both `modules/pearcord-platform` and `modules/pearcord-agentctl` to refresh local `file:` module links.
 If `wait-ready` returns `ESTARTUP_TIMEOUT`, run `agentctl log-tail --lines 120` and inspect startup blockers before retrying.
 `doctor` includes `listeningEvidence` pulled from `pearcord.log` so attached-mode diagnostics can confirm the latest worker-side `agentctl listening` line and whether it matches expected host/port.
+`ping` includes `handshake` metadata (`appVersion`, `platformVersion`, `moduleGraphHash`, `pearcordModuleCount`) for runtime module-graph parity checks.
 
 ## CLI reference
 
@@ -115,6 +116,8 @@ TCP clients receive push events:
 
 - `{ "event": "state", "view": … }` after IPC / poll
 - `{ "event": "sidecar", "payload": { "type": "error"|"log", … } }` when worker forwards UI errors or warn+ log lines
+- `{ "event": "sidecar", "payload": { "type": "agentctl-heartbeat", … } }` periodic liveness heartbeat
+- `{ "event": "sidecar", "payload": { "type": "agentctl-startup", "phase": "...", … } }` startup checkpoints
 
 ### Examples
 

PLATFORM_ROADMAP.md

@@ -20541,11 +20541,11 @@ P2P-first phase: Hyperswarm guild mesh, `GUILD_SYNC` bundles, join/recovery pipe
 | P661-30 | Agentctl: add JSON error code taxonomy (`ECONN_REFUSED`, `EMODULE_MISSING`, etc.) | [x] |
 | P661-31 | Agentctl: include actionable next-step hints per error code | [x] |
 | P661-32 | Agentctl: support `--wait-listening` for attached runs in scripts | [x] |
-| P661-33 | Runtime: emit heartbeat event over agentctl stream for liveness checks | [ ] |
-| P661-34 | Runtime: emit startup phase checkpoints for agentctl readiness debug | [ ] |
-| P661-35 | Runtime: include module graph hash/version in agentctl handshake metadata | [ ] |
-| P661-36 | Platform: add bounded startup health metric for agentctl service bind latency | [ ] |
-| P661-37 | Platform: add span for agentctl server startup (`agentctl.server.start`) | [ ] |
+| P661-33 | Runtime: emit heartbeat event over agentctl stream for liveness checks | [x] |
+| P661-34 | Runtime: emit startup phase checkpoints for agentctl readiness debug | [x] |
+| P661-35 | Runtime: include module graph hash/version in agentctl handshake metadata | [x] |
+| P661-36 | Platform: add bounded startup health metric for agentctl service bind latency | [x] |
+| P661-37 | Platform: add span for agentctl server startup (`agentctl.server.start`) | [x] |
 | P661-38 | Agentctl: add synthetic onboarding journey smoke with live attached mode | [ ] |
 | P661-39 | Agentctl: add synthetic guild open/channel select/live composer focus journey | [ ] |
 | P661-40 | Agentctl: add synthetic DM open + send + mark-read attached smoke | [ ] |
@@ -22128,7 +22128,7 @@ Absorbed into Phase 273 (P273-5–P273-8, P273-11–P273-12). See Phase 274 for
 
 ### Changelog
 
-- **2026-06-02** — v0.8.640: Phase 661 agentctl reliability slice completed (`preflight`, `doctor`, `wait-ready`, `ping` bounded retry/`--wait-listening`, structured JSON error taxonomy + remediation hints, `PEARCORD_AGENTCTL=1` guidance checks, host/port/token diagnostics in ping output, `doctor` listening-evidence scan from worker log, one-shot live harness docs, platform dependency guards `test:deps`/`test:imports`/`ci:deps` for `pearcord-*` import declaration + resolve parity, and docs runbook refresh in `AGENTCTL.md` + `modules/pearcord-agentctl/README.md` + `modules/pearcord-platform/README.md` including local install-order guidance).
+- **2026-06-02** — v0.8.640: Phase 661 agentctl reliability slice completed (`preflight`, `doctor`, `wait-ready`, `ping` bounded retry/`--wait-listening`, structured JSON error taxonomy + remediation hints, `PEARCORD_AGENTCTL=1` guidance checks, host/port/token diagnostics in ping output, `doctor` listening-evidence scan from worker log, runtime `agentctl-heartbeat` + `agentctl-startup` sidecar events, ping handshake metadata (`moduleGraphHash`/versions), bounded startup metric + `agentctl.server.start` span, one-shot live harness docs, platform dependency guards `test:deps`/`test:imports`/`ci:deps` for `pearcord-*` import declaration + resolve parity, and docs runbook refresh in `AGENTCTL.md` + `modules/pearcord-agentctl/README.md` + `modules/pearcord-platform/README.md` including local install-order guidance).
 - **2026-06-01** — v0.8.625: Phase 653 — production mesh federation live (`_logMeshFederationLive` in mesh replication diagnostics export, dev-log **federation-live** filter, agentctl `runMesh8PeerFanoutJourney` 3-peer × 8-token fanout, `PRODUCTION_MESH_FEDERATION.md`, `test:phase653-production-mesh-federation`). Platform roadmap complete except P5-6 mobile companion.
 - **2026-06-01** — v0.8.591: Phase 628 — pins hub depth (`#pin-hub-panel-live` mesh note + active channel context, **pin-errors** excludes `guild.search` bleed, dev-log clipboard `pinActiveChannelName`/`pinHubMeshLive`, platform pin spans `activeChannelId` re-verify, agentctl pin/unpin `refreshView`, `test:phase628-pins`). Phases 629–652 replication track closed via existing guild-sync/mesh bundles.
 - **2026-06-02** — v0.8.624: Phase 652 — live mesh churn at scale (`guild.mesh.churn.scale`, topic pool ninth-peer cap smoke, mesh replication diagnostics IPC, federation aggregate heal pulse on Explore, composer autofocus after hub ingest, `runPartitionHeal3PeerLiveJourney`, `runMeshChurnScaleSoakJourney`, dev-log **mesh-churn-scale**, server-rail sync dot animations, `MESH_CHURN_SCALE.md`, `test:phase652-live-mesh-churn`). Phase 653 planned (50 items).