# Observability Redesign Implementation Instructions

## Role

You are Opus in the distribution platform orchestration flow. Codex is the
manager. Snarky owns product acceptance. You own layout and visual design
decisions and are the only role allowed to edit code during this phase.

## User Direction

The user clarified that the git setup required for the Opus implementation
branch is Opus responsibility.

If `/Users/agra/projects/distribution` is not yet a git repository, initialize a
local git repository, create a clean baseline commit from the current workspace,
and then create or switch to branch:

```txt
opus/observability-redesign
```

Use branches only. Do not create a worktree.

## Primary Task

Implement the observability dashboard redesign from:

```txt
.agents/runs/2026-06-02-observability-redesign/opus-proposal.md
```

The dashboard lives at:

```txt
.agents/observability/
```

It is served by:

```txt
.agents/scripts/observe.mjs
```

## Allowed Edit Scope

Application/dashboard edits are limited to:

- `.agents/observability/index.html`
- `.agents/observability/styles.css`
- `.agents/observability/app.js`
- `.agents/scripts/observe.mjs`
- `.agents/runs/2026-06-02-observability-redesign/implementation-log.md`

Creating `.git/` and committing/switching branches is allowed as setup for this
phase. Do not edit root mock files such as `index.html`, `styles.css`, or
`app.js`.

## Required Product Shape

Implement the proposal's operational cockpit direction:

- Replace the four metric cards with a compact sticky status bar and a "Now"
  command band.
- Make the first viewport answer what is active, whether anything is blocked or
  stalled, who is working, what happened recently, and what the manager should do
  next.
- Pin active-agent liveness with status, lease countdown, heartbeat age, and
  clear warning/dead states.
- Keep progress readable but bounded; it must not dominate the whole page.
- Keep the UI dense, calm, and operational. Avoid marketing layout, hero copy,
  decorative nesting, and generic dashboard fluff.
- Support desktop and mobile without text overlap.

## Required Interactions

- Keep the existing `/api/status` polling model and static vanilla app.
- Add a one-second local ticker for freshness, heartbeat age, and lease
  countdown text.
- Add pause/resume for auto-refresh.
- Keep the last good render on fetch error; do not replace the progress log with
  an error message.
- Add progress expand/collapse.
- Preserve progress bottom-stick behavior and show a jump control when new lines
  arrive while the user is scrolled up.
- Make run rows selectable. If the API supports `?run=`, use it to refocus
  progress for the selected run; otherwise degrade gracefully.
- Add click-to-copy for run id, branch, and progress path with a short copied
  state.

## Required Server/API Additions

Make only additive, optional changes:

- Per-agent liveness fields:
  - `lease_remaining_ms`
  - `heartbeat_age_ms`
  - `lease_expired`
  - `is_active`
- Summary fields:
  - `active_role`
  - `health`
- Active progress fields:
  - `modified_at`
  - `total_lines`
  - `truncated`
- Support `/api/status?tail=N&run=<id>` so selected runs can show their own
  progress.
- In progress selection, prefer the newest candidate progress artifact by mtime.

The frontend must remain missing-field safe.

## Validation Expectations

Before finishing, run:

```sh
node --check .agents/scripts/observe.mjs
node --check .agents/observability/app.js
node .agents/scripts/status.mjs --tail 20
```

If possible, start or reuse the local server and verify:

```sh
curl http://127.0.0.1:4317/api/status?tail=5
```

Write a short final implementation report to:

```txt
.agents/runs/2026-06-02-observability-redesign/implementation-log.md
```

Include changed files, validation commands/results, unresolved risks, and the
current git branch/status.
