Apply task evidence end to end

Traceability

• Spec ID: 2026-09-01-task-evidence-upload-end-to-end
• Status: Implemented
• Refs: 2026-09-01-task-evidence-upload, 2026-09-01-organization-harness-dashboard

Intent

Close the gap between the two halves that already existed: better-harness upload plan prepared a reviewable packet but could never send it, and the Dashboard rendered an upload section whose input was a hard-coded empty array. Nothing carried evidence from one to the other, and the page itself showed a single snapshot taken when its server process started.

This spec makes the loop real and keeps every existing consent boundary. The prepared plan remains the only thing that names a destination, the packet contract is unchanged, and applying a plan is a separate, explicit command rather than a side effect of preparing one.

Acceptance Scenarios

• AC-1 — Apply is explicit and plan-directed: better-harness upload apply --plan <file> posts a validated plan to the endpoint recorded inside that plan. The destination cannot be supplied or overridden on the command line, so applying cannot redirect evidence somewhere the reviewed plan did not name. --help returns without reading the plan or using the network.
• AC-2 — Receipts are verifiable: the destination returns a better-harness.task-evidence-upload-receipt/v1 whose body is bound by a canonical SHA-256 digest. apply rejects a receipt whose digest, destination, or organization does not match the applied plan, and reports a rejected or unreachable destination as a failure with no receipt.
• AC-3 — Idempotent acceptance: the packet digest is the storage key and the idempotency key. Sequential or concurrent re-application of the same plan reports one accepted result and duplicate thereafter, preserves the first acceptance time, and leaves exactly one stored record.
• AC-4 — The destination validates before it stores: the local /api/upload route requires JSON and rejects an invalid or tampered plan, a plan addressed to another endpoint, an oversized body, and an organization outside BETTER_HARNESS_UPLOAD_ORGANIZATIONS when that is configured. A rejected request stores nothing.
• AC-5 — Accepted evidence reaches the Dashboard: the collector reads stored records from the uploads directory and projects their packets into evidencePackets. A record that cannot be parsed or validated is reported as an unavailable source rather than silently dropped.
• AC-6 — Data is current: the collected input is reused for a bounded refresh window (BETTER_HARNESS_REFRESH_MS, default 30s) and recollected after it, aged from the end of a collection rather than its start. A failed collection is not cached. Evidence written after the server started appears without restarting the process.
• AC-7 — Every analyzable host is collected: session evidence defaults to all supported session platforms rather than two, BETTER_HARNESS_PROVIDERS narrows that set, and asset inventory covers only hosts with an inventory adapter so an unsupported host is skipped instead of reported as a failure.
• AC-8 — A session limit actually bounds work: an unset limit analyzes every eligible session with all-eligible; a configured BETTER_HARNESS_SESSION_LIMIT switches to latest-n so the limit applies instead of being ignored.
• AC-9 — Observed context usage is shown: contextUsage from the analyzed host is carried into the Dashboard input when its status is observed, and is absent otherwise.

Input and Output Contract

upload apply consumes a prepared plan and produces:

{
  "kind": "better-harness.task-evidence-upload-receipt",
  "schemaVersion": 1
}

carrying acceptedAt, state (accepted or duplicate), the plan's destination, a receiptId, the packetDigest and planDigest it answers, and a receiptDigest over that body.

The destination stores one better-harness.task-evidence-upload-record/v1 per packet digest, holding the receipt and the plan it accepted. The uploads directory is BETTER_HARNESS_UPLOADS, or <workspace>/.better-harness/uploads.

Non-goals

• Authentication, tenancy, RBAC, approval workflow, or a deployed control plane. The bundled endpoint is a local destination for the local Dashboard.
• Protobuf/Buf ingestion, PostgreSQL, or object storage.
• Changing the task evidence input, packet, or plan contracts.
• Automatic upload: preparing a plan still never sends anything, and applying one is always a separate command.
• Live push or websocket refresh. The page recollects on request within a bounded window.

Plan and Tasks

1. Extend the upload contract with a digest-bound receipt, its validator, and a content-addressed storage key.
2. Add upload apply to the capability CLI with an injectable fetch, a bounded timeout, receipt verification against the applied plan, and stable diagnostics; register it in the root CLI.
3. Add a local upload store shared by the destination route and the collector, with idempotent writes and reporting reads.
4. Add the /api/upload route handler that validates before it stores.
5. Replace the collector's empty packet list with stored records, widen its provider default, make its limit meaningful, and carry observed context usage.
6. Replace the Dashboard's permanent process-lifetime cache with a bounded refresh window behind a testable seam.
7. Cover the chain with focused tests: contract, store, CLI, collector, the real route handler over a loopback port, and a browser run whose evidence is applied through the real CLI.

Test and Review Evidence

• AC-1, AC-2, AC-3: npx vitest run test/cli/task-evidence-upload.test.mjs covers plan-directed posting, idempotency-key headers, receipt mismatch, rejected and unreachable destinations, tampered plans, and receipt tampering.
• AC-3, AC-4, AC-5: npm test -w @qoder-ai/harness-ui runs the upload store tests, including concurrent applies, and an end-to-end test that drives the real CLI against the real route handler over a loopback port, then projects the stored packet into the Dashboard model. Wrong media types, endpoint mismatches, tampering, and disallowed organizations are rejected before storage.
• AC-6, AC-7, AC-8: focused cache, collector-argument, refresh-window, and workspace-resolution tests in packages/harness-ui/test/local-data.test.mjs.
• AC-5, AC-9: npm run harness-ui:test:browser applies fixture evidence through upload plan and upload apply against the running Dashboard in its global setup, then asserts the applied task is visible on the page.