distribution/.agents/runs/2026-06-02-observability-redesign/implementation-instructions.md

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:

opus/observability-redesign

Use branches only. Do not create a worktree.

Primary Task

Implement the observability dashboard redesign from:

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

The dashboard lives at:

.agents/observability/

It is served by:

.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:

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:

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

Write a short final implementation report to:

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

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