# Agent and Cluster Observability

audience: AI coding agents first.

status: IDLE
task IDs: recovered owner request; link registry ID when created
source request: Make Overdeck observability useful: unified activity logs, agent/build/session/node visibility, time-series charts, drill-down, and terminal attach. Never substitute notification-delivery metadata for actual event evidence.

## Outcome

Overdeck shows what work ran, where, when, and with what result across Factory, harness, Claude, CDX, bots, builds, Git, incidents, and k3s/SSH nodes. Owner can filter, search, chart, drill into one run, inspect logs, and attach to its terminal.

## Acceptance criteria

- Inventory every authoritative event/log source before UI work.
- Normalize event identity, project, category, host/node, session/run, timestamps, lifecycle, result, and evidence link without fabricating missing fields.
- Use `@platform-modules/ui-primitives` `DataTable` for searchable/sortable activity rows and existing platform primitives elsewhere.
- Row click opens run/session detail with individual logs and lifecycle evidence.
- Charts support 1h, 1d, 3d, 7d, 30d, all-time; project/category filtering; active-agent, log-volume, commit, bot, build, and incident activity.
- Cluster view maps sessions/builds/agents to nodes and links to agent detail and tmux attach.
- Notification suppression is not an incident. Record underlying event; do not harass owner with “notification failed” noise.
- Both themes work; report and product surfaces do not regress to light-only.
- Production is browser-proven with honest live data.

## Preserved context

- Existing report: `/home/user/.local/share/overdeck/reports/2026-08-08-session-report.html`.
- Earlier activity/log/session UI tasks may contain reusable delivery; recover before rebuilding.
- Existing Prometheus/node_exporter/Grafana stack supplies host metrics but does not replace agentic event semantics.
- `live-report-sync` owns current status truth. This plan owns product observability and drill-down UX.

## Constraints

- UI MUST obey `.claude/skills/od-ui-dev/SKILL.md` and use platform primitives first.
- Do not dump raw logs as the primary UX.
- Do not claim observability from registration, suppression, or stale task labels.
- Keep SSH and k3s execution sources visible during incremental migration.
- This plan must not block emergency offload or Factory restoration.

## Execution steps

1. Recover prior observability brainstorm, shipped components, schemas, and task receipts.
2. Inventory authoritative event sources and retention/query limits.
3. Write normalized event/detail/time-series contract.
4. Implement ingestion and deterministic correlation before presentation.
5. Build DataTable activity view, detail drill-down, charts, node/session map, and terminal attach links from reusable components.
6. Verify source counts, lifecycle transitions, filters, theme behavior, and browser paths.
7. Land and deploy; record owner-visible URL and proof.

## Current receipt

Request recovered from owner corpus. Existing partial observability/report work is not yet reconciled against this acceptance contract. No named worker.

## Next executable action

Recover existing observability code/tasks and inventory authoritative event sources; update preserved WIP before implementation.