truf-server/openspec/changes/add-worker-operator-experience/specs/worker-admin-experience/spec.md

ADDED Requirements

Requirement: Separate assignment and scan outcomes

The worker administration list SHALL display assignment transport outcome, scan outcome, and diagnostic count as separate fields and SHALL not label last_error_code as the complete scan error category.

Scenario: Accepted scan has an error outcome

• WHEN a reservation has a durable accepted bundle whose target scan status is error
• THEN the list SHALL show assignment accepted, scan error, and the diagnostic count/categories

Scenario: Assignment expires before scan ingestion

• WHEN a reservation expires without an accepted bundle
• THEN the list SHALL show assignment expired, scan outcome unavailable, and the expiry diagnostic

Requirement: Assignment detail timeline

Each worker assignment row SHALL link to a detail page that reconstructs issued, phase-progress, bundle/terminal report, receipt, ingestion, queue settlement, and projection timestamps that exist for that assignment.

Scenario: Administrator opens an active assignment

• WHEN progress events exist for an unresolved assignment
• THEN the page SHALL show current phase, phase age, last progress age, scan deadline, assignment deadline, and ordered prior phases

Scenario: Administrator opens a settled assignment

• WHEN the assignment has been accepted and projected
• THEN the timeline SHALL distinguish acceptance, ingestion, queue settlement, and projection completion rather than collapsing them into one completion time

Requirement: Clickable diagnostic detail

The assignment detail page SHALL list diagnostics and SHALL provide human summary, canonical envelope JSON, raw body view, process log view, transformation metadata, and copy/download actions for each diagnostic.

Scenario: Diagnostic body is complete

• WHEN an HTTP diagnostic contains an untruncated body
• THEN the raw-body view SHALL identify it as complete and display the captured content and metadata

Scenario: Diagnostic material is truncated

• WHEN body or log material was size-truncated
• THEN the view SHALL prominently display original/stored sizes, hash, and truncation state

Scenario: Legacy scan error has no diagnostic envelope

• WHEN an older scan has only existing errors.raw_error or result metadata
• THEN the detail page SHALL display those fields as legacy evidence and SHALL not invent a new envelope

Requirement: Diagnostic filtering and grouping

The admin UI SHALL filter independently by source, time, worker/device, assignment outcome, scan outcome, phase, category, stable code, and retryability and SHALL group repeated diagnostic fingerprints without hiding individual occurrences.

Scenario: Administrator filters rate-limit errors

• WHEN category rate_limit and a time window are selected
• THEN results SHALL include matching diagnostics regardless of whether their assignments were accepted or prebundle-failed

Scenario: Repeated diagnostics are grouped

• WHEN multiple diagnostics share a fingerprint
• THEN the UI SHALL show aggregate count and affected assignments while retaining links to each occurrence

Requirement: Worker fleet status

The admin UI SHALL display each worker's configured cap, active slots, current phases, package identity, latest contact/progress ages, pending local-recovery indication when reported, and known idle/backoff reason.

Scenario: Worker is scanning without recent API contact

• WHEN a worker has an active assignment and recent progress events but its authentication contact timestamp is old
• THEN fleet status SHALL show active progress rather than classifying the worker as idle solely from contact age

Scenario: Worker cannot claim due to capacity

• WHEN the server rejects claims because a pipeline capacity axis is closed
• THEN fleet status SHALL show the capacity reason instead of a generic offline/idle state

Requirement: Deadline and duration administration

The runtime editor and worker observability pages SHALL explain effective scan, upload, and assignment deadlines and SHALL show p50/p95/p99 duration metrics with sample counts by source and phase.

Scenario: Administrator edits a source assignment deadline

• WHEN a per-source TTL candidate is previewed
• THEN the editor SHALL show the effective policy, validation relationship to scan/upload bounds, and that only future assignments are affected

Scenario: Administrator compares policy to observations

• WHEN sufficient phase-duration samples exist
• THEN the page SHALL show the configured deadline alongside source-specific percentile values without automatically changing configuration