truf-server/openspec/changes/add-web-operations-control-plane/tasks.md

1. PostgreSQL Operations Authority

• 1.1 Add an additive runtime-safety migration for the singleton operations control row, durable operation records, and append-only audit events
• 1.2 Add schema invariants, final-cutover checks, import/export handling, and migration-count fixtures for the new tables
• 1.3 Implement ScannerDB control-state reads and revision-checked discovery, dispatch, and drain mutations with atomic audit insertion
• 1.4 Enforce the discovery gate transactionally in provider admission, discovery retry, and Docker tag-resolution paths without blocking ingestion-derived work
• 1.5 Enforce the dispatch gate transactionally in remote reservation admission while preserving status, terminal report, upload, replay, expiry, and ingestion
• 1.6 Implement drain progress queries and reconciliation from live assignments and pre-commit result bundles
• 1.7 Add concurrent PostgreSQL tests for pause/admission races, stale revisions, restart persistence, drain completion, and uninterrupted uploads

2. Discovery-Only Server Producers

• 2.1 Extract a discovery-only cycle for GitLab, DockerHub, and HuggingFace that performs provider work and enqueueing without scan preparation or claiming
• 2.2 Preserve DockerHub page cursors, retry-lane processing, tag resolution, and immutable target admission in the discovery role
• 2.3 Add an authenticated discovery-producer runtime bootstrap role and Supervisor managed-process type with structured state
• 2.4 Change the default distributed core profile to exactly GitLab, DockerHub, and HuggingFace and remove GitHub from that profile
• 2.5 Add tests proving each producer runs with backlog, respects persistent pause, reports safe state, and never enters local scanner/claim/bundle code

3. Protocol-2 Multisource Assignments

• 3.1 Replace the Git-only assignment switch with source adapters that declare queue source, worker platform, planning kind, snapshot validation, and package capability
• 3.2 Implement GitLab exact_git_v1, DockerHub docker_direct_v1, and HuggingFace huggingface_space_v1 execution-snapshot models and canonical validation
• 3.3 Generalize ScannerDB claim recovery and result-ready validation for the three planning kinds while retaining fixed reservation and device fences
• 3.4 Update source selection to try other compatible eligible queues while issuing at most one assignment per admission request
• 3.5 Advance worker/package manifests to protocol 2 with explicit source/platform/planning capabilities and fail-closed manifest validation
• 3.6 Update Windows and Linux worker clients to dispatch the bound Docker and HuggingFace scan platforms and validate protocol-2 snapshots before execution
• 3.7 Retain protocol-1 status, upload, terminal-report, receipt, and immutable reconciliation for existing assignments while refusing new protocol-1 claims
• 3.8 Add unit and PostgreSQL integration tests for capability matching, fallback, replay, expiry, stale upload rejection, source aliases, and legacy completion

4. New-Source End-to-End Canaries

Implementation guardrail: provider accessibility is finalized by the worker. New per-target server preflight/proof state, broad worker-environment credential scrubbing, or other source-specific defensive infrastructure requires separate operator approval and an explicit OpenSpec requirement/task before implementation.

• 4.1 Implement public DockerHub immutable-digest assignment execution without server registry-credential or layer-plan transport
• 4.2 Implement tokenless HuggingFace Space assignment execution with explicit discovery visibility filtering and non-retryable inaccessible results, without leaking server discovery credentials
• 4.3 Extend packaged-worker verification for Windows and Linux with synthetic DockerHub and HuggingFace claim-to-ingestion flows
• 4.4 Add bounded canary configuration and assertions for search, enqueue, claim, worker-classified provider failures, upload, ingestion, projection, replay, expiry, and drain without adding per-target server access proofs

5. Shared Runtime Document Validation

• 5.1 Add a side-effect-free bounded YAML loader with duplicate-key rejection and secret-safe errors
• 5.2 Define strict configuration, core-profile, auth-pool, reference-integrity, package-capability, and deployment-path validation
• 5.3 Use the shared validator in preview, runtime startup, and secrets import without weakening existing runtime security checks
• 5.4 Implement fixed config/secrets candidate storage with private durable writes, SHA-256 compare-and-swap, and bounded redacted diffs
• 5.5 Add validation and concurrency tests for unknown keys, duplicate keys, invalid references, stale active hashes, stale candidates, and error redaction

6. Typed Supervisor and Operations Services

• 6.1 Extend Supervisor control protocol with structured runtime/source snapshots and exact managed-source lifecycle actions
• 6.2 Add bounded log-tail actions keyed only by allowlisted managed source IDs and reject generic web command forwarding
• 6.3 Implement operation creation, lifecycle transition, bounded result reconciliation, and append-only audit service methods
• 6.4 Add Supervisor and operation-service tests for malformed actions, unknown sources, log bounds, restart races, and content-free audit records

7. Web Operations Console

• 7.1 Add trusted Caddy operator-header stripping/injection and backend actor validation tied to the private edge marker
• 7.2 Add shared admin navigation and overview page with bounded runtime, queue, assignment, bundle, control, and operation health
• 7.3 Add Search pages and exact forms for persistent discovery controls plus typed producer lifecycle and interval actions
• 7.4 Add Workers/Dispatch pages and exact forms for pause/resume, drain start/cancel/progress, package compatibility, users, devices, and assignments
• 7.5 Add Supervisor status/action and bounded log pages without shell, path, or generic command inputs
• 7.6 Add config and plaintext secrets preview/save/apply pages with no-store rendering, revision/hash conflicts, and no value leakage outside the editor
• 7.7 Add durable operation-status and bounded paginated audit pages that survive runtime restart
• 7.8 Add admin API and browser tests for routes, methods, exact form shapes, actor spoofing, Origin/CSRF, stale forms, navigation, CSP, and secret non-retention

8. Managed File Service

• 8.1 Define logical managed roots and per-root list/read/create-replace/delete permissions with bounded path, listing, and byte limits
• 8.2 Implement descriptor-relative Linux traversal with no-follow component opens and rejection of absolute, dot, drive, backslash, symlink, hardlink, and special-file targets
• 8.3 Implement bounded download, durable compare-and-swap create/replace, and expected-hash delete with private temporary files and directory fsync
• 8.4 Add typed Files pages/forms and content-free mutation audit events while keeping config, secrets, database, sockets, agent metadata, and raw bundles excluded
• 8.5 Add adversarial traversal, encoded traversal, symlink-swap, hardlink, special-file, limit, concurrent-replacement, and forbidden-root tests

9. Privileged Host Operations Agent

• 9.1 Implement a root-owned Unix-socket agent with peer-credential checks and a closed request schema containing only operation ID, action enum, and expected hashes
• 9.2 Implement singleton locking, persisted-operation verification, host-side revalidation, fixed-path backups, and atomic config/secrets replacement
• 9.3 Implement fixed runtime/edge stop and recreation plus bounded health verification for Supervisor, PostgreSQL, Worker API, ingester, and projector
• 9.4 Implement byte-identical automatic rollback and failed-hold behavior without arbitrary services, paths, commands, or retry loops
• 9.5 Add systemd socket/service units, fixed host-managed config/candidate directories, permissions, and deployment installer validation
• 9.6 Add crash-boundary and hostile-request tests for validation, backup, replacement, restart, health failure, rollback success, rollback failure, and request-field injection

10. Deployment Migration and Verification

• 10.1 Update container, code-authority, package, Caddy, systemd, and deployment fixtures for all new modules, profiles, routes, headers, sockets, and fixed managed paths
• 10.2 Add an offline migration/rollback test proving the previous image can coexist with additive tables after protocol-2 work is drained
• 10.3 Run focused unit and PostgreSQL integration suites, packaged worker verification, edge E2E, browser coverage, strict OpenSpec validation, and diff checks
• 10.4 On the approved production host, deploy one exact supported ingress profile with discovery and dispatch paused, verify protocol-2 packages plus runtime/admin/edge/agent health, complete one reconciled lifecycle operation and one successful automatic rollback drill, and only then issue or resume new work
• 10.5 Run the bounded DockerHub end-to-end canary and retain evidence for queue authority, ingestion, projection, expiry/replay, and drain
• 10.6 Enable GitLab and public HuggingFace only after canary gates pass, confirm GitHub remains excluded, and document rollback evidence
• 10.7 Add exact root-owned standalone-edge-v1 and shared-host-edge-v1 deployment profiles without changing the host-agent request schema
• 10.8 Add the shared-host Compose/Caddy route confinement and profile-specific lifecycle, installer, and denylist validation while preserving standalone behavior
• 10.9 Add dual-profile tests, deployment documentation, strict validation, and real hardened Caddy/Compose checks