fn describe_lifecycle_is_unknown(describe: Option<&Value>) -> boolExpand description
GET /api/v1/muxspect/find?block_id=X or ?agent=X — Ext 4 of
docs/reports/REPORT_MUXSPECT_MUXLOG_CROSS_CHANNEL_INSPECTION_2026_08_22.md:
“which running instance(s), if any, have a controller or subagent
dispatch matching block_id/agent X” — the query that debugging session
needed and had no tool for, ending in manual filesystem/env-var
archaeology across every channel by hand.
Checks THIS instance first (host tier, no network) via the same
ProcessBroker::list() handle_muxspect_list uses (so “found” here
means the same thing muxspect list would show, not a different
existence check invented for this endpoint) and, for an agent query,
reactive_handler.list_agents() (same source handle_muxspect_conversations’s
host tier and verify-sender use).
Then checks every OTHER channel via the shared reactive registry
(resolve_shared_reactive_dir + list_all_shared — the exact mechanism
handle_muxspect_conversations’s cross-channel tier already uses, see
that handler’s own doc comment for the security rationale) WITHOUT any
network call at all for basic existence: AgentEntry already carries
block_id/agent_id/channel/local_url, so a match there already
answers “which channel” before any forwarding happens. Only a MATCHED
cross-channel entry gets a forwarded describe call (same
single-forwarded-hop / timeout discipline as the conversations handler)
to fill in process/controller detail — unmatched channels cost nothing.
Always 200 — zero results is a legitimate answer (“not found on this
host, in any known channel”), not an error, same posture as every other
handler in this file. results can have more than one entry only if the
same block_id/agent name somehow exists in more than one place at once
(a real, worth-surfacing anomaly, not something to silently collapse to
the first match).
Cross-channel block_id scope (reagent P2 on PR #2745): the
cross-channel tier only searches the shared AgentEntry registry —
agent-registered blocks. A plain shell/terminal block, or any other
non-agent controller, in a DIFFERENT channel is not findable by
block_id here (the host tier above has no such limit — it searches
this instance’s FULL ProcessBroker::list(), any controller type).
Reaching a non-agent controller cross-channel would need a remote
/api/v1/muxspect/list-style forward-and-filter, not just a registry
lookup — out of scope for this change; see
SPEC_MUXSPECT_CROSS_INSTANCE_FIND_2026_08_22.md’s Non-goals.
True when a forwarded describe response’s process_status.lifecycle
reads "unknown" — broker::process::Lifecycle::Unknown’s own doc
comment: “no controller found for this block_id at all.” A None
input (the forward itself failed/timed out) is NOT the same as this —
deliberately returns false for that case, since “we couldn’t ask” is
not the same claim as “we asked and it’s confirmed gone.” Pure
(extracted from the async handler above) for direct unit testing —
reagent P1 on PR #2745 found the un-extracted inline version reported
“found”: true unconditionally, with no test coverage of the “gone but
still registered” case at all.