feat(desktop): visualize agent graph topology

[orangeCatDeveloper]

Fixes #2596

Agent Graph hides dependency paths and bounded operator diagnostics, so users must open child sessions to understand blocked or incomplete work.

The panel previously flattened an already-bounded graph projection and discarded most inspection fields. Snapshot lifecycle ordering also changed DOM order, while generic scrolling could move the outer panel instead of only the topology viewport.

This adds a stable directed topology with routed skip-level edges and keeps the list as an accessible alternative. Selection follows both views without live-refresh jumps; exact work omissions, wait bounds, activation/claim/activity metadata, and canonical status semantics remain visible. Operator details sit beside their selected list row, and controls expose unique disclosure relationships without stretching visible labels.

The topology node retains one reviewed native button because the Astryx Button label wrapper cannot represent the multi-row graph card; the generated inventory enforces that exact path and callsite count. The Electron E2E covers the materialized client projection through renderer, preload IPC, main, Runtime Host, and SQLite, but does not claim graph execution or reconciliation coverage.

Evidence

Before — dependencies are not represented:

After — dependency, status, work, wait, and selection are visible:

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

After
tests 1573
pass 1573
fail 0
Electron Agent Graph E2E: 1 passed (3.3s)
Full Electron E2E: 68 passed, 1 skipped, 0 failed
Real-window programmatic smoke: Electron exited with code 0

AI use

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

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

Checklist

• Tests cover the change and fail without it
• Lint, format, typecheck, build, ASF headers, Astryx inventory, Desktop tests, and Electron E2E pass locally

Does this PR entail a change in behavior?

• Yes — described 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.

[orangeCatDeveloper]

Addressed every review finding at exact head a8bde94df.

• Stable provisioning order and visual DOM order keep node positions and keyboard focus deterministic.
• Topology scrolling now changes only its own two-axis viewport; list/topology switches and collapse/expand retain and reveal selection without live-refresh jumps.
• Skip-level edges route around intermediate nodes.
• Work selection prefers the newest requested item, and work/readiness omissions report exact bounded counts.
• Inspection now exposes dependency identities, activation times/records/run IDs, claim intent/session/time/run IDs, and recent activity signals/times/run IDs.
• Status dots use the shared Astryx vocabulary, visible status text remains at narrow widths, and hover is distinct from selection.
• The native graph-card button exception is documented and guarded by exact path and count.

Final local evidence:

Desktop: 1573 passed, 0 failed
Agent Graph unit suites: 27 passed, 0 failed
Electron Agent Graph E2E: 1 passed
Full Electron E2E: 68 passed, 1 skipped, 0 failed
Lint / format / typecheck / build / ASF headers / Astryx inventory: PASS
Real-window programmatic smoke: Electron exited with code 0