setupGatewayChat is the only production constructor of a Router and it runs in the Gateway, which owns no container pool, no poll loop and no channel manager. The producers wired to those three built report sections no reply could carry, and /status' own description of itself claimed all five fields. The health source now carries the broker connection and the chat-model outcome, the two facts the answering process holds. The tests for the deleted producers go with them, replaced by one that pins the served shape with a pool and a daemon present in the boot. Corrects docs/prds/status-health-surface.md, where the intro, the Phase 2 summary and the rendering bullet all claimed the five-line surface.
9.1 KiB
/status health surface
Status: Finalised
Beads issue: archie-core-wp9s
A reported field must have a truthful source. /status reports broker
connectivity and the last chat-model call; the container pool, last poll and
channel state have no source in the process that answers the command, so they
are left out rather than faked.
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
/tasks: new command,gateway.ChatTaskSummaryextended withStage/Attempt/ParkReason/UpdatedAt(all already persisted onstore.Task, zero new instrumentation), sorted actionable-first./status: itemized per-status task counts replaced with one aggregateQueue: 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 "Runtime (provider/model)" under Phase 2's "Truthful or absent" for where that stands now.
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. Both open questions were settled (see "The two decisions"). The health section reports the broker connection and the last chat-model call; the three facts the answering process cannot see are covered under "Truthful or absent".
Verified as cheap against the tree
- Broker connectivity.
internal/infrastructure/eventbus/nats.Clientalready exposesCoreConn() (*nats.Conn, error)(client.go). The underlyingnats.Conn(nats.go) has its ownStatus()/IsConnected(). AClient.Connected() boolwrapper is a few lines. - Container pool.
container.Poolalready tracksactive intunder its own mutex (pool.go) but has no public accessor. APool.Active() intgetter is a few lines. - Last poll. Nothing tracks this. The daemon's poll loop
(
internal/daemon) needs onelastPollAt time.Timefield (atomic or mutex-guarded, matching the pool's own pattern) set at the top of each poll tick, with a getter. - Queue depth. Covered by Phase 1.
The two decisions
- Provider reachability is last-known outcome, never a live probe. A chat
command must not perform a blocking network call in its handler, and a probe
reports the probe's reachability rather than the daemon's.
/statustherefore prints what actually happened -- the last chat-model call's model, age and error, or "no calls attempted yet" when there has been none. Implemented asproviderOutcomeRecorder, written once insendChatTurn(the single point every chat-model call in the process passes through) and read back bynewStatusHealth. Nothing on this path dials a provider. The existing live model reachability check (readiness.go'smodelReachProbe) is unchanged and stays where it belongs: on/health/detailed, off the chat path. - Channel state comes from the existing ChannelManager.
/statusreadsstatus.Manager.Snapshot()-- the same ledger the dashboard and the readiness probe already use -- rather than re-deriving channel health from each adapter. No method was added to theChannel/Gatewaycontract.
Phase 2
- Broker connectivity.
internal/infrastructure/eventbus/nats.ClientgainedConnected() bool, which reads the connection the process already holds. The standalone Gateway (which dials NATS itself for task actions) reports the same fact from that connection. - Container pool.
container.Pool.Active()andPool.Cap()read the pool's own counter and configuredmax_concurrency-- not a Docker listing, which would include containers this pool does not own. A cap of zero means unlimited, so/statusrenders the count alone rather than "1/0 active". - Last poll.
daemon.Daemon.LastPollAt()reports when the most recent poll pass began; both poll paths (pollfor single-identityRun,pollForIdentityforrunIdentities) stamp it. A pass that hangs leaves the stamp stale, which is the signal -- stamping completion instead would leave a wedged poller looking healthy. - Queue depth. Covered by Phase 1.
- Rendering.
gateway.formatHealthrenders one line per reported fact (Broker:,Containers:,Channels:,Chat model:,Last poll:) between the queue line and the runtime block. A/statusreply carriesBroker:andChat model:: the Gateway is the only process that serves a Router, and it holds neither a container pool, a poll loop nor a channel manager. The other three lines render when a report carries them. The broker source is a function rather than a captured value because the connection differs by composition: the daemon's shared eventbus client in one process, the Gateway's own task-actions connection in the other.
Truthful or absent -- what is deliberately not reported
- Version. Still excluded:
/versionowns it, and duplicating it back into/statusis the exact "answers something available elsewhere in chat" complaint this ticket exists to fix. - Sections the standalone Gateway process cannot see. The daemon owns the
poll loop, the container pool and the channel manager; the Gateway process
owns none of them. Its
/statusreports broker and chat-model health and omits pool, polling and channels rather than printing zeroes. Aggregating them across processes would need a new daemon RPC -- a new subsystem, out of scope here. For the same reason the chat-model line is per process: the daemon records the turns it runs (Telegram, email, webhook), the Gateway records the web chat's, and the two do not pool outcomes. Each line is true of the process answering the command. Decided: they stay per-process. Pooling them would mean a new daemon↔gateway health RPC for one status line, and a per-process line is true where an aggregate would be a claim about a process the answering one cannot see. The composition root therefore builds the health source from the broker connection and the chat-model recorder alone: a producer for a daemon-owned fact would build a section no reply can carry. - A channel's failure reason can outlive the failure.
status.Managerkeeps the last non-emptyDetailacross state changes, and that one field carries both a descriptor's standing caveat and a runtime failure reason, so a channel that failed and later recovered can still render the old reason. Splitting the two belongs at the producer (the manager and its descriptor), not in this reader, which reads the field exactly as the dashboard does. - Container pool when Docker is unavailable. Composition leaves
containerPoolnil, so the section is absent. Naming a reason would mean carrying Docker's startup error into the health surface. - Runtime (provider/model). Phase 1 left this block in place; it is still
here. It is static config that
/modeland/whoamialready answer, so it is the only line in/statusthat this ticket's own rule says should not be there -- but the maintainer reads/statusdaily to see the active model at a glance, and one command answering both "is archie well" and "what is it running on" is worth that duplication. Decided: keep it. It is a settled product decision, not an oversight; do not remove it as a mechanical follow-up. /agentscopy. The menu still advertises "List tasks being worked" whileRouter.Agentsis never wired (archie-core-mxls), so that one published description does not match what its command does. Deleting, rewiring or redefining/agentsis that bead's call and is not folded in here.
Packages this touches (Phase 2)
internal/infrastructure/eventbus/nats:Client.Connected().internal/container:Pool.Active(),Pool.Cap().internal/daemon:lastPollAt/markPoll/LastPollAt().internal/gateway:health.go(health contract + renderer),Router.Health,formatStatus.internal/app/archied:status_health.go(the composition-root bridge),ProviderOutcomesthreaded throughtelegramSetupinto every turn runner, andsendChatTurnrecording each call's outcome.internal/domain/messaging+internal/channels/telegram:/statusand/tasksdescriptions, which now describe both commands' actual jobs on both published surfaces.