4.2 KiB
id, title, status, wave, depends_on, plan, spec
| id | title | status | wave | depends_on | plan | spec |
|---|---|---|---|---|---|---|
| 02-publish-agent-runtime-availability | Publish agent runtime availability | done | 1 | plan.md | ../../specs/platform/requirements/agent-runtime-availability.md |
Task 02: Publish agent runtime availability
Intent
Turn an unexpected standalone agentctl exit into an authoritative,
sanitized, replayable runtime snapshot without changing process ownership or
backend health semantics.
Acceptance
- The launcher invokes one unexpected-exit callback for zero or non-zero child
exits that were not caused by
Stop; intentional shutdown invokes none. - The availability tracker is concurrency-safe, does not expose startup as
available, becomes available only after health and authentication succeed,
and transitions monotonically to unavailable with reason
agentctl_exitedwithin one boot. - Connected clients receive
system.agent_runtime.status_changed, and clients that subscribe later receive the latest full snapshot. - Every authenticated boot/app-state response includes
agentRuntime; the unauthenticated minimal boot payload does not disclose it. - Process error text, PID, and exit code remain logs-only.
- No
/health, child restart, token, PID, lifecycle-client, or execution rebinding behavior changes.
TDD sequence
- Add launcher tests for unexpected non-zero exit, unexpected clean exit, and intentional stop; confirm callback cases fail.
- Add tracker tests for internal startup, post-handshake availability, one-way unavailable transition, concurrent snapshot reads, stable reason, and event publication; confirm RED before the tracker exists.
- Add boot-state and gateway tests for live broadcast and late subscription replay, including auth-disabled/authenticated versus unauthenticated boot payloads.
- Implement the callback, tracker, composition, event/action constants, boot hydration, and replay wiring. Rerun focused tests and refactor only after GREEN.
Files likely touched
apps/backend/internal/agent/runtime/agentctl/availability.goapps/backend/internal/agent/runtime/agentctl/availability_test.goapps/backend/internal/agent/runtime/agentctl/launcher/launcher.goapps/backend/internal/agent/runtime/agentctl/launcher/launcher_test.goapps/backend/internal/backendapp/agentctl.goapps/backend/internal/backendapp/helpers.goapps/backend/internal/backendapp/boot_state.goapps/backend/internal/backendapp/helpers_test.goapps/backend/internal/events/types.goapps/backend/pkg/websocket/actions.goapps/backend/internal/gateway/websocket/system_notifications.goapps/backend/internal/gateway/websocket/system_notifications_test.goapps/backend/cmd/kandev/main.go
Dependencies
None.
Parallelism
parallel-safe with Task 01. This task does not touch ACP normalized stream or
adapter files.
Verification
cd apps/backend && go test ./internal/agent/runtime/agentctl/... ./internal/backendapp ./internal/gateway/websocket
Inputs
- Existing launcher
monitorExitintentional-shutdown classification. - Existing
system/jobs.Tracker,SystemEventBroadcaster, boot-state builder, andHub.AddUserSubscriptionListenerreplay patterns. - ADR 0019 supervisor-owned restart boundary.
Output contract
Record focused test results and the final public JSON/action shape. Note any startup-composition file that differs from the likely list because wiring moved.
Results
Implemented the launcher callback, concurrency-safe monotonic tracker, event
and WebSocket action, authenticated boot hydration, and user-subscription
replay. The wire snapshot is {status, reason?, occurred_at?}; startup is
unpublished, healthy startup is {status: "available"}, and the only failure
transition is {status: "unavailable", reason: "agentctl_exited"} with a UTC
occurrence timestamp. Raw process errors, PID, and exit code remain logs-only.
RED coverage was added for the missing launcher callback, tracker publication and monotonicity, boot hydration/authenticated boundary, and live/replayed WebSocket delivery. Focused verification passed:
go test ./internal/agent/runtime/agentctl/... ./internal/backendapp ./internal/gateway/websocket
562 passed in 4 packages