feat(desktop): visualize agent graph topology

[orangeCatDeveloper]

Fixes #2596

Summary

Agent Graph shows operator status but its flat list hides which work depends on what, so chains and waiting paths require opening child Sessions one by one.

The panel already receives bounded operators, edges, work previews, and readiness data, but previously rendered only independent rows. This adds a read-only directed topology with visible status/work/wait context, keyboard-selectable operator inspection, and the existing list as a narrow-window and accessibility alternative. Stable provisioning order, selected-node viewport anchoring, and routed skip-level edges keep the topology readable as snapshots change. Operator inspection exposes bounded work, dependency, activation, claim, and activity records with explicit omission counts, and snapshot invalidation refreshes those details.

Native scrolling keeps oversized bounded snapshots reachable. Pan/zoom and arbitrary cyclic layout remain outside this operational DAG view.

Design-system review

The topology node intentionally uses one native <button> JSX callsite. Astryx Button wraps children in an overflow: hidden; text-overflow: ellipsis span, which prevents the heading, work preview, and wait reason from becoming grid items. The surface inventory keeps this file visible through an explicit one-callsite exception; a second native button restores the blocker, as covered by the policy test.

Verification

Before — dependencies are not represented:

After — the dependency edge, node status, work preview, and wait reason are visible:

• npm run lint
• npm run format:check
• npm run build
• npm run typecheck
• npx knip --workspace apps/desktop
• npx knip --workspace packages/ui
• npm run astryx:surface-inventory
• npm run check:asf-headers
• Agent Graph suites: 40 passed
• Desktop suite: 1586 passed
• Runtime Host isolated rerun: 1267 passed, 9 skipped; the full parallel workspace run reported an unrelated Runtime Host failure under load

AI use

Select exactly one:

• No generative tool made a substantive contribution
• Generative tooling made a substantive contribution

Tool(s) and scope: OpenAI Codex implemented the topology UI, tests, inventory policy, verification evidence, and PR draft.

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck and the affected suites pass locally

Does this PR entail a change in behavior?

• Yes — described under Summary above
• No

[Astro-Han]

I reviewed this PR at exact head 36ab826552e61aa2de066aafa23260042ee101dd (base 6762085e, merge-base 38f0a275, 12 files +965−28, 1 commit).

Spec: NO-GO — 2×P1 + 2×P2

1. P1 — refresh can rearrange existing nodes and lose the visual locus. layoutAgentGraph rebuilds row order from each fresh operators array (apps/desktop/src/renderer/agent-graph-topology.tsx:67-75,93-107); the bounded read model moves nodes between live/terminal partitions on status change and re-sorts terminals (packages/runtime/src/stream-graph-read-model.ts:982-1000). The selection ID survives, but the selected node can jump to a different row/offscreen, and a newly inserted upstream node shifts descendants' columns. This violates the stable-layout / no-needless-viewport-jump expectation for a live-updating graph.

2. P1 — “inspection” discards most bounded inspection data. The panel calls graphs.inspectOperator (agent-graph-panel.tsx:382-387) but renders only the first work and aggregate edge/activation counts (:713-738), dropping inbound/outbound identities, activation status/times/run, claims, recent records, and omission counts. The API already exposes this bounded data, so the panel does not satisfy inspecting it.

3. P2 — skip-level dependencies can disappear behind intermediate nodes. All edges are center-to-center Béziers without obstacle routing (agent-graph-topology.tsx:157-173) rendered below nodes. In a same-row chain A→B→C→D plus a declared A→D, the long edge runs under B/C and appears interrupted or absent.

4. P2 — work/wait semantics imply completeness when partial. Preview takes the first globally visible matching work regardless of status/recency, otherwise the operator ID (agent-graph-topology.tsx:46-51). Wait text takes only the first waiting readiness / first wait (agent-graph-panel.tsx:764-789) and never signals omitted readiness/waits, so multiply-blocked or truncated nodes look singly and completely explained.

The findings were reproduced by static inspection; the isolated worktree lacked installed tsx, so no local runtime harness was claimed.

Standards: NO-GO — 1×P3

• P3 — undocumented native-button exception contradicts committed Astryx governance. A new raw <button> is added at agent-graph-topology.tsx:184; docs/astryx-surface-file-inventory.md:247 says any raw button/input/select with an Astryx twin is a blocker. The generator 132-139,301-325 special-cases this filepath as aligned while the legend remains unconditional. The wrapper limitation and exact-count guard are credible, but the exception class should be documented or an Astryx composition seam added. Other metadata, evidence, tokens/motion, inventory, and layering pass.

Other checks: git diff --check passes; test, audit, package, windows_recovery, and owner macOS/Windows checks are all terminal SUCCESS for this exact head; OPEN / MERGEABLE / BLOCKED / REVIEW_REQUIRED, no reviews/comments, head did not drift.

What I did not check: full local Desktop suite beyond the checks noted.

Gate: exact head has P1/P2 findings and therefore cannot be approved or merged until the stable-layout/inspection and edge/work-wait issues are fixed and the Astryx exception is documented or removed.

---

Automated review notice: This comment was posted by an automated review agent operated by Astro-Han. It is not an independent human review and does not replace one.