truf-server/openspec/changes/add-worker-operator-experience/proposal.md

Why

Remote workers execute and settle production work correctly, but they behave as opaque background processes: an owner cannot tell whether a slot is downloading, scanning, cleaning up, bundling, uploading, stalled, or close to its deadline, while the admin console conflates assignment failures with scan errors. The next change should turn the proven worker engine into an understandable operator-facing product without building temporary UI around the current incomplete status and error fields.

What Changes

• Add a worker-specific supervisor and CLI for install, foreground run, detached start, graceful stop, status, attach, live logs, local history, and diagnostics.
• Add one versioned assignment phase/event model shared by local status, attach, server progress, history, diagnostics, and admin rendering.
• Apply a hard local scan-stage deadline across permit acquisition, scanner execution, cleanup, filtering, and result staging instead of bounding only the scanner subprocess path.
• Make assignment deadlines observable and configurable as server-owned global and per-source policy, with explicit scan, upload, and assignment deadline semantics.
• Add a versioned diagnostic envelope for provider responses, process failures, exceptions, timeout state, structured categories/codes, and bounded raw body/log material.
• Persist local worker events and diagnostics as JSON/JSONL and transmit the same diagnostic model through terminal reports and accepted result bundles.
• Replace the ambiguous assignment-table Error category presentation with distinct assignment outcome, scan outcome, diagnostic count, and a clickable detail/timeline view.
• Add machine-readable --json/NDJSON output and human-readable status/attach views without inventing progress percentages.
• Add a from-zero operator guide covering installation, first start, attach/status, interpreting phases and errors, graceful drain/stop, recovery, update, and troubleshooting.
• Do not add a separate masking/redaction feature or silently generalize captured diagnostics. Storage bounds and any unavoidable transformation must be explicit in diagnostic metadata.

Capabilities

New Capabilities

• worker-operator-supervisor: Lifecycle CLI, detached supervision, attach/status/log/history/doctor commands, local projections, and operator documentation.
• worker-progress-deadlines: Canonical assignment phases, local and server progress events, full scan-stage watchdog behavior, deadline policy, and duration percentile observability.
• worker-diagnostics: Unified diagnostic envelope, local diagnostic archive, terminal/bundle transport, taxonomy, retention bounds, and exact transformation metadata.
• worker-admin-experience: Assignment and scan outcome separation, diagnostic persistence/querying, clickable timeline/detail UI, and human/machine-readable diagnostic views.

Modified Capabilities

None. There is no synchronized main-spec directory in this workspace; the new capabilities define the operator-facing contract over the existing distributed worker implementation.

Impact

• Worker client/bootstrap/package entrypoints and generated Windows/Linux launchers.
• Scanner subprocess lifecycle, scan-slot ownership, cleanup, bundle staging, and local runtime state.
• Worker API progress, prebundle report, result-bundle, and assignment-status contracts.
• PostgreSQL reservation, scan, error, diagnostic, and observability queries/schema.
• Server-rendered worker administration pages and runtime deadline editor fields.
• Windows process supervision and Linux/WSL/Docker foreground/detached operation.
• Worker package tests, protocol tests, fault-injection tests, admin UI tests, and operator documentation.