docs(gateway): propose /status Phase 2 health checks

Phase 1 (archie-core-wp9s) shipped /tasks and the /status queue-depth
aggregate. This documents the remaining ask -- broker connectivity,
provider reachability, channel state, container pool, last poll --
split into cheap wiring (nats.Conn.Status(), container.Pool's
already-tracked active count, a new last-poll timestamp) versus two
real product decisions (live-probe vs last-known-outcome for provider
reachability; the ChannelManager-backed shape for channel state).

Proposed resolution, awaiting Sam's sign-off before Phase 2 lands.
This commit is contained in:
sam committed 2026-09-03 07:17:59 +10:00
1 parent b698322505
commit 9b9539fe81
1 file changed
+108
+108
View File
@@ -0,0 +1,108 @@
# /status health surface -- what's shipped, what's proposed
**Status:** Phase 1 shipped 2026-09-03 (archie-core-wp9s). Phase 2 below is
a **proposed resolution, awaiting Sam's sign-off** -- not yet implemented.
## Background
`archie-core-wp9s` ("/status and /tasks have the wrong division of labour")
asked for two things: `/tasks` owning the live per-task work view, and
`/status` owning daemon health -- "broker connectivity, provider
reachability, channel state, container pool, queue depth, last poll,
version" -- with neither duplicating the other or static config available
elsewhere (`/model` already lists active provider/model).
## Phase 1 -- shipped
- `/tasks`: new command, `gateway.ChatTaskSummary` extended with
`Stage`/`Attempt`/`ParkReason`/`UpdatedAt` (all already persisted on
`store.Task`, zero new instrumentation), sorted actionable-first.
- `/status`: itemized per-status task counts replaced with one aggregate
`Queue: N in flight (...)` line (running/waiting/parked only -- queued and
terminal states excluded as not a health concern). Runtime
(provider/model) is temporarily left in place; see the open question
below.
Not touched: `/agents` (`gateway.AgentReader`/`Router.Agents`) is a separate,
pre-existing command that already has the right shape for "list active
work" but is never wired to a real implementation in any composition-root
call site (`bootstrap.go`, `telegram_setup.go`) -- it always answers "Agent
listing is not configured." in production. That is a standalone bug
(`archie-core-mxls`), not folded into this work: deciding whether to wire
it, repurpose it, or delete it in favor of `/tasks` is Sam's call, not
something to resolve by implication here.
## Phase 2 -- health checks, verified against the actual tree
Each bullet below was checked against real code before being called cheap
or not; nothing here is guessed.
### Cheap -- no design decision needed, straightforward to add
- **Broker connectivity.** `internal/infrastructure/eventbus/nats.Client`
already exposes `CoreConn() (*nats.Conn, error)`
(`client.go:134`). The underlying `nats.Conn` (nats.go) has its own
`Status()`/`IsConnected()`. A `Client.Connected() bool` wrapper is a few
lines.
- **Container pool.** `container.Pool` already tracks `active int` under
its own mutex (`pool.go:90`) but has no public accessor. A
`Pool.Active() int` getter is a few lines.
- **Last poll.** Nothing tracks this today. The daemon's poll loop
(`internal/daemon`) needs one `lastPollAt time.Time` field (atomic or
mutex-guarded, matching the pool's own pattern) set at the top of each
poll tick, with a getter.
- **Queue depth.** Already shipped in Phase 1.
### Not cheap -- needs a decision before coding
- **Provider reachability.** No existing check anywhere. The only way to
answer "is the provider reachable" is a real network call, which means:
a `/status` invocation either pays that latency and cost every time
(bad -- `/status` should be instant, matching `/model`'s and `/tasks`'
own current behaviour), or `/status` reports the **last** call's
outcome (success/failure/never-called) rather than probing live. The
latter needs a small success/failure counter or timestamp recorded at
the one place LLM calls already go through (`ai-sdk` responder path),
not a new probe. Recommend: last-known-outcome, not live probing --
but this is a real product tradeoff (freshness vs. cost) worth Sam's
explicit sign-off before it's built into a command he uses daily.
- **Channel state.** `channels.Channel` (embeds `gateway.Gateway`:
`Name()/Start()/Stop()`) has no connectivity/health method today, and
telegram/email/webhook each manage their own connection lifecycle
independently. Answering "is Telegram actually connected" needs either
(a) a new method on the `Channel`/`Gateway` contract every implementation
must satisfy, or (b) each channel self-reporting into a shared registry
the daemon already holds (`ChannelManager` -- `bootstrap.go` already
calls `b.channelManager.MarkStarting/MarkRunning/MarkFailed` per
channel). (b) is very likely the right shape since `ChannelManager`
already exists and already tracks exactly this kind of state for the
dashboard; needs a read method exposed to `/status`. Flagging as
"needs a decision" only because it touches a contract multiple
implementations satisfy, not because the shape is unclear -- ChannelManager
is the obvious answer.
- **Version.** Deliberately **not** proposed for `/status`: `/version`
already owns this (`Router.Version`, `handleVersion`), and duplicating it
back into `/status` would reintroduce the exact "answers something
available elsewhere in chat" complaint this ticket exists to fix.
## Recommendation
Ship the three cheap items (broker connectivity, container pool, last
poll) as a mechanical follow-up alongside Phase 1's `Queue:` line --
same shape, same non-duplication reasoning, no new design surface. Land
provider reachability and channel state only after Sam confirms the
last-known-outcome approach (provider) and the ChannelManager-read
approach (channel), since both are choices about a command's behaviour
he already has strong, specific opinions about.
## Packages this touches (Phase 2)
- `internal/infrastructure/eventbus/nats`: `Client.Connected() bool`.
- `internal/container`: `Pool.Active() int` (and `Pool.Cap() int` for
"N/M" display, from the already-configured `MaxConcurrency`).
- `internal/daemon`: last-poll timestamp, read accessor.
- `internal/gateway`: `formatStatus` gains the new lines; `Router` gains
whatever read surfaces back them (mirrors `StatusReader`'s existing
pattern -- a narrow interface, not a daemon-internals handle).
- Provider reachability and channel state: packages TBD pending the two
decisions above.