@evolvingmachines/evolve 0.0.60 → 0.0.61

package/spec/openapi.yaml

@@ -2082,6 +2082,16 @@ paths:
           — `text/plain` named `<trialId>_<stream>.log` for the raw logs,
           `application/json` named `<trialId>_trace-atif.json` for the
           ATIF trajectory; an absent one still answers the JSON `{"log": null}`.
+        - `filesystem`: the run's FILE SYSTEM as one gzipped tarball — the
+          same archive `GET /api/trials/{trialId}/filesystem/archive`
+          streams for `path=/` (captured after the run, with `MANIFEST.tsv`
+          naming the unchanged image files it does not carry; live from the
+          box while it runs); `source=` forces one, and a source that is not
+          there is 409 `filesystem_state` — never an empty archive. The
+          archive route's own codes answer here too: 422
+          `feature_unsupported` for a live tree too large to leave the box
+          inside the capture budget, 503 `provider_unreachable` when the
+          provider does not answer.
         - `agent-home`: the agent home tree as JSON — the utf8 TEXT VIEW of
           the captured bytes
           (`{"files": {"<sandbox-path>": "<text>", ...} | null}`; a file that
@@ -2150,6 +2160,7 @@ paths:
               - trace-atif   # the normalized ATIF v1.7 trajectory
               - trajectory   # x-wave: 2 — the harness-native session file slot
               - agent-home
+              - filesystem   # the run's file system as one .tar.gz (the archive route's answer)
         - name: format
           in: query
           description: >
@@ -2195,13 +2206,22 @@ paths:
               schema:
                 type: string
                 format: binary
-                description: '`format=tgz` delivery of agent-home.'
+                description: '`format=tgz` delivery of agent-home, or the `filesystem` archive.'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `stream=filesystem` with `source=live` while
+            the box is gone, or `source=capture` before a capture exists
+            (details carry the requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '413':
           description: >
             The agent-home JSON text view is over the server's whole-read
@@ -2211,10 +2231,27 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — `stream=filesystem` on a live box whose
+            provider has no live view, or whose subtree cannot leave the box
+            inside the capture budget (details.cause names it).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '429':
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
+        '503':
+          description: >
+            `provider_unreachable` — `stream=filesystem` and the box's
+            provider did not answer; retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
 
   /api/trials/{trialId}/files:
     get:
@@ -2332,33 +2369,44 @@ paths:
         '500':
           $ref: '#/components/responses/InternalError'
 
-  /api/trials/{trialId}/regrade:
-    post:
+  /api/trials/{trialId}/filesystem:
+    get:
       tags: [trials]
-      operationId: regradeTrial
-      summary: Regrade one trial
+      operationId: getTrialFilesystem
+      summary: The trial's file system — which source it has
       description: |
-        Verifier-only re-run of a single trial. **The response is a Job** — a
-        one-trial regrade job with `source_jobs` recording the provenance.
-        The source trial is immutable. A trial of an UPLOADED job is refused
-        (`job_uploaded`, 409): no recorded verifier inputs exist to re-run.
+        The Files surface of one trial (the file system family, one shape
+        under every run owner: trials, analyses, task checks — and the task
+        package as a fourth, read-only owner). `state` says what the
+        listing, read, search, archive and change routes will answer from:
+        `live` — the box is running and the routes read it as it changes;
+        `captured` — the run ended and its file system was kept, the same
+        routes read the kept tree; `capturing` — the run just ended and the
+        capture is still being written; `none` — nothing to read yet (a
+        queued run, a run older than the feature, a capture that failed —
+        `capture.status` says which). `box` names the running box and its
+        role, `watcher` how change events arrive (`native` from the
+        provider, `poll` from the folders the viewer declared open), and
+        `capture` the kept tree's record: when, after which phase, how many
+        entries and changed files, `ready` | `incomplete` (`left_out` names
+        what did not fit the budget) | `failed`.
       parameters:
         - $ref: '#/components/parameters/TrialId'
       responses:
-        '202':
-          description: The regrade job.
+        '200':
+          description: The file system's state.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Job'
+                $ref: '#/components/schemas/FilesystemStatus'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
-        '409':
+        '503':
           description: >
-            `job_not_terminal`, `no_regradable_trials`, or
-            `regrade_source_ineligible`.
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
           content:
             application/json:
               schema:
@@ -2368,296 +2416,2042 @@ paths:
         '500':
           $ref: '#/components/responses/InternalError'
 
-  /api/trials/{trialId}/retry:
-    post:
+  /api/trials/{trialId}/filesystem/files:
+    get:
       tags: [trials]
-      operationId: retryTrial
-      summary: Retry one settled trial
+      operationId: listTrialFilesystemFolder
+      summary: List one folder of the trial's file system
       description: |
-        Run ONE settled trial again. **The response is a Job** — a one-trial
-        retry job inheriting the source job's config, with `source_jobs`
-        recording `action: "retry"`; view it with `GET /api/jobs/{jobId}`
-        (the 202 carries a `Location` header naming it). The source trial is
-        immutable.
-
-        The same operation as `POST /api/jobs/{jobId}/retry` with
-        `{"trial_ids": [this]}` — one selection rule, one builder, one
-        fingerprint — kept as its own door because the trial page (and
-        Harbor's hosted `trial retry <id>`) address the trial, not the job.
-        The source JOB may still be running: a settled trial's facts are
-        final, so "run it again" is well-defined the moment it settles. A
-        trial of an UPLOADED job is refused (`job_uploaded`, 409).
-
-        Supports `Idempotency-Key` — the identical fingerprint the job-level
-        door computes for this one-trial selection, because it IS the
-        identical request.
+        One page of a folder, sorted by name, paged with `cursor` (the last
+        name served) and `limit` (default 500, max 1000). `source` forces
+        `live` or `capture`; omitted, whichever the run has (`state` on the
+        status route). Every entry carries its type (`dir` | `file` |
+        `symlink` — with `target` — | `other`), size, mtime, mode and owner;
+        `changed` and `phase` say whether the run created or modified it
+        and in which phase (null when not known for the source); on a
+        captured listing `captured: false` marks a file the run never
+        touched, which only the image holds — it lists but does not open.
+        The kernel trees (`/proc`, `/sys`, `/dev`) are never listed.
       parameters:
         - $ref: '#/components/parameters/TrialId'
-        - $ref: '#/components/parameters/IdempotencyKey'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
       responses:
-        '202':
-          description: >
-            The retry job. `Location` names it (`/api/jobs/{jobId}`).
-          content:
-            application/json:
-              schema:
-                $ref: '#/components/schemas/Job'
         '200':
-          description: Idempotent replay of an identical retry request.
+          description: One page of the folder.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Job'
+                $ref: '#/components/schemas/FilesystemListing'
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
-        '402':
-          description: Out of credits (`insufficient_credits`).
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/filesystem/files/{path}:
+    get:
+      tags: [trials]
+      operationId: readTrialFilesystemFile
+      summary: Read one file of the trial's file system, raw bytes
+      description: |
+        RAW BYTES of one file — application/octet-stream, byte fidelity, no
+        translation (whether it is text is the reader's call: the first
+        4 KiB, a NUL byte means binary). A standard single `Range` header
+        (`bytes=a-b`, `bytes=a-`, `bytes=-n`) reads a slice and answers 206
+        with `Content-Range`; `Accept-Ranges: bytes` advertises it; a
+        malformed or multi-range header is the typed 400, an out-of-file
+        range the 416. An unranged read above the deployment's whole-read
+        ceiling is the typed 413 (`invalid_input`, param `Range`, details
+        `size_bytes` / `max_unranged_bytes`) — read it in slices.
+        `X-Source` names the source that answered, `X-Ms` the server time.
+        A symlink reads as its target (one hop). A path the file system
+        does not hold is 404 `not_found`; on a captured read, a file the
+        run never touched is 404 `not_captured` (only the image holds it).
+        A stream that breaks after the headers ends with an aborted
+        connection, never a partial body delivered as success.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - name: path
+          in: path
+          required: true
+          description: The absolute box path, e.g. `app/work/main.py` for `/app/work/main.py` (the leading slash is the route's).
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: Range
+          in: header
+          description: Optional single byte range (`bytes=a-b` / `bytes=a-` / `bytes=-n`).
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The whole file (`X-Source`, `X-Ms`).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '206':
+          description: The requested byte range (`Content-Range` states position and size).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
         '409':
           description: >
-            Trial still live (`trial_not_settled` — QUEUED, RUNNING, and
-            SCORING trials cannot be retried), or `idempotency_key_reused`.
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-        '429':
+        '413':
           description: >
-            Two conditions, distinguished by code: `rate_limited` (the
-            standard throttle — honor `Retry-After`), and `quota_exceeded`
-            — the owning organization's `max_queued_trials` ceiling would
-            be crossed by this job (`details`: `{quota, limit, used,
-            requested, org}`; the message starts `hosted quota exceeded:`).
-            No `Retry-After`: the wait is not a known number. Nothing was
-            created; retry once the organization's queue has drained, or
-            ask the platform administrator to raise the ceiling. A ceiling
-            of 0 means the organization is paused.
+            An unranged read above the whole-read ceiling (`invalid_input`,
+            param `Range`; details `size_bytes` / `max_unranged_bytes`).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '416':
+          description: >
+            Range selects nothing inside the file (`invalid_input`;
+            `Content-Range` carries `bytes */<size>`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
 
-  /api/trials/stop:
-    post:
+  /api/trials/{trialId}/filesystem/search:
+    get:
       tags: [trials]
-      operationId: stopTrials
-      summary: Stop selected running trials or trace analyses
+      operationId: searchTrialFilesystem
+      summary: Search the trial's file system for text
       description: |
-        Stops individual in-flight trials without cancelling their job: each
-        trial's sandbox is killed and the trial is settled with its spend read
-        from the gateway. Only the caller's own trials; ids belonging to
-        someone else are reported in `not_found` (existence is never leaked).
-        Idempotent — already-terminal trials are reported as such and left
-        untouched.
-
-        Trace-analysis ids ride the same `trial_ids` array — what each id is
-        gets resolved server-side, so a client never partitions a selection.
-        A running analysis has its analyzer box killed and settles `failed`
-        with failure phase `stopped`, its own spend read from the gateway; a
-        queued one settles the same way before any box boots (nothing minted,
-        nothing spent). Stopped analyses come back in `stopped_analyses` with
-        their settled rows; the caller's already-settled analyses land in
-        `already_terminal` and foreign or unknown ids in `not_found` — the
-        trials' refusal semantics, id for id.
-      requestBody:
-        required: true
-        content:
-          application/json:
-            schema:
-              $ref: '#/components/schemas/StopRequest'
+        Content search: `q` is the text (or, with `regex=true`, the
+        pattern), `path` the folder to search under (default `/` — the
+        whole box, `scope: "box"`, which can take seconds; a folder answers
+        `scope: "path"` in well under a second), `limit` the hit cap
+        (default 200, max 1000). `truncated: true` means more hits exist or
+        the search budget ran out — narrow the path or the text. Live: the
+        box is searched as it is; captured: the kept text is searched, and
+        `image_files_excluded: true` says files the run never touched were
+        not searchable. Binary files never hit.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - name: q
+          in: query
+          required: true
+          description: The text to find; a regular expression with `regex=true`.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemPath'
+        - name: regex
+          in: query
+          description: Treat `q` as a regular expression (default false — a plain substring).
+          schema:
+            type: boolean
+            default: false
+        - $ref: '#/components/parameters/FilesystemLimit'
+        - $ref: '#/components/parameters/FilesystemSource'
       responses:
         '200':
-          description: Per-trial outcome of the stop request.
+          description: The hits found.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/StopResponse'
+                $ref: '#/components/schemas/FilesystemSearchResult'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '429':
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
 
-  # ===========================================================================
-  # Analyses — trace-analysis runs as a first-class list
-  # ===========================================================================
-
-  /api/analyses:
+  /api/trials/{trialId}/filesystem/events:
     get:
-      tags: [analyses]
-      operationId: listAnalyses
-      summary: List trace-analysis runs
+      tags: [trials]
+      operationId: streamTrialFilesystemEvents
+      summary: Change events while the trial's box lives (SSE)
       description: |
-        Every trace analysis the caller may read, newest first, cursor-paged.
-        Items are the same `TrialAnalysis` object a trial serves as its
-        LATEST analysis (`Trial.analysis`) — here every analysis answers,
-        earlier waves included, each carrying the trial, job, and task it
-        judged. Harbor has no analysis list (their analyze writes a local
-        `analysis.json` per trial dir); hosted, the analyzer's run is a
-        record of its own and this is its catalog.
-
-        Visibility follows the analyze verb (`POST /api/jobs/{jobId}/analyze`)
-        one relation deeper: an analysis belongs to the analyzed trial's job.
-        `scope=my` (the default) lists analyses of jobs you created;
-        `scope=shared` lists analyses of your organizations' jobs that
-        teammates created. Nothing is public, so Harbor's `all` is refused.
-        An API key sees exactly what its owner may read — there is no
-        wider scope.
-
-        Filters are server-side and compose with the cursor.
+        Server-sent events. `event: state` first (`{state, box}`), then
+        `event: fs` per change (`{seq, t, path, type: create|write|remove|
+        rename, source: watch|poll}`, `id: <seq>`), `event: ping` every
+        15 s. Resume with `Last-Event-ID: <seq>` (or `?after=`): the events
+        after it replay when the server still holds them; when it does not,
+        a fresh `state` frame is the signal to relist the open folders.
+        On a provider without a native watcher (`watcher: "poll"` on the
+        status route) events come from polling the folders declared with
+        `POST …/filesystem/watch`, so declare them. A `state` frame follows
+        every change of state; the stream ends once the file system settles
+        (`captured` or `none`).
       parameters:
-        - $ref: '#/components/parameters/Limit'
-        - $ref: '#/components/parameters/Cursor'
-        - $ref: '#/components/parameters/ListScope'
-        - name: job
-          in: query
-          description: Only analyses of this job's trials.
+        - $ref: '#/components/parameters/TrialId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume after this event seq.
           schema:
             type: string
-            format: uuid
-        - name: status
+        - name: after
           in: query
-          description: >
-            Filter by the analysis's own lifecycle word (the lowercase
-            ladder `TrialAnalysis.status` speaks) — repeatable and/or
-            comma-separated; an unknown word is refused (`invalid_input`)
-            with the ladder in `details.valid_statuses`.
+          description: The same as `Last-Event-ID`, for clients that cannot set headers.
           schema:
-            type: array
-            items:
-              type: string
-              enum: [queued, running, completed, failed]
-          explode: true
+            type: string
       responses:
         '200':
-          description: One page of analyses.
+          description: The event stream.
           content:
-            application/json:
+            text/event-stream:
               schema:
-                $ref: '#/components/schemas/AnalysisPage'
+                type: string
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '429':
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
 
+  /api/trials/{trialId}/filesystem/watch:
+    post:
+      tags: [trials]
+      operationId: watchTrialFilesystem
+      summary: Declare the folders the viewer has open
+      description: |
+        The folders whose changes the event stream must report on a
+        provider without a native watcher (`watcher: "poll"`): idempotent —
+        the body's `paths` REPLACES the set; an empty set stops polling. At
+        most 8 folders at once (a bigger set is the typed 400 naming the
+        bound). On a provider with a native watcher the set is accepted
+        and unused. Refused with `filesystem_state` when the box is gone.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FilesystemWatchRequest'
+      responses:
+        '200':
+          description: The set in force.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemWatchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/filesystem/changes:
+    get:
+      tags: [trials]
+      operationId: listTrialFilesystemChanges
+      summary: The files the trial changed
+      description: |
+        The flat list of what the run created, modified or removed since its
+        box started, with `phase` (`setup` | `agent` | `verifier`); `total`
+        and `changed_bytes` are the whole list's, `items` one page (`cursor`
+        = an opaque position, `limit` default 500, max 1000); `phase=`
+        narrows to one phase. Captured: stored with the kept tree. Live: the
+        box start listing against a fresh one, seconds per call; a box whose
+        start listing was not stored is the typed 422.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: phase
+          in: query
+          description: Only changes of one phase (default all).
+          schema:
+            type: string
+            enum: [setup, agent, verifier, all]
+            default: all
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the changed-files list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemChanges'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — the shape or the provider has no live view
+            of what was asked (details.cause names it).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/filesystem/archive:
+    get:
+      tags: [trials]
+      operationId: downloadTrialFilesystemArchive
+      summary: Download one subtree of the trial's file system as a .tar.gz
+      description: |
+        A gzipped tarball of the subtree under `path` (default `/`, the
+        whole tree), streamed. Captured: only the kept bytes ride; the
+        files the run never touched are listed in `MANIFEST.tsv` at the
+        archive root with `captured=false`. Live: read out of the running
+        box under the capture budget — a subtree too large to leave the box
+        inside it is refused up front, 422 `feature_unsupported` with the
+        size in `details.cause`; a read-out that still stalls past the
+        budget aborts the connection, never a truncated archive delivered
+        as success. `X-Source` names the source. A folder the file system
+        does not hold is 404 `not_found`.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+      responses:
+        '200':
+          description: The archive (`Content-Disposition` names it `<id>_filesystem.tar.gz`).
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — the provider has no live view of what was
+            asked, or the live subtree cannot leave the box inside the
+            capture budget (details.cause names it, with the size).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/logs:
+    get:
+      tags: [trials]
+      operationId: getTrialSandboxLog
+      summary: One page of a sandbox log stream of the trial
+      description: |
+        The box's own streams, recorded while it runs and kept after:
+        `agent` (the harness's stdout/stderr), `verifier` (the verifier
+        command's) and `system` (the box's system log — only when the job
+        asked for it, `JobCreate.system_log`). `setup` and `metrics` are
+        named but not recorded today. Lines are `{seq, t, fd: out|err, line}`;
+        `cursor` is an opaque position, `limit` default 1000, max 1000. A
+        stream the platform holds nothing for answers an empty page whose
+        `reason` says why — never an error.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - name: stream
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/SandboxLogStream'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the stream.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SandboxLogLines'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/logs/events:
+    get:
+      tags: [trials]
+      operationId: streamTrialSandboxLogs
+      summary: Sandbox log lines as they arrive (SSE)
+      description: |
+        Server-sent events over every stream at once: `event: line`
+        (`{stream, seq, t, fd, line}`, `id: <stream>:<seq>`), `event: state`
+        on open and on every change of the box's state, `event: ping` every
+        15 s. Without
+        `Last-Event-ID` every stream replays from its beginning and then
+        follows; with `Last-Event-ID: <stream>:<seq>` that stream resumes
+        after the seq the paged GET handed out. Once the box is gone and
+        every recorded line has been sent, the stream ends — the paged GET
+        is the reader after that.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume one stream after `<stream>:<seq>`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/procs:
+    get:
+      tags: [trials]
+      operationId: getTrialProcs
+      summary: The trial's box process list (live only)
+      description: |
+        The processes running in the box right now, as one text listing
+        (`ps` sorted by memory; on an image without `ps`, the same table
+        read from `/proc`, its first line saying so). Live only: once the
+        box is gone the answer is 409 `filesystem_state`.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+      responses:
+        '200':
+          description: The listing.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SandboxProcs'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+
+  /api/trials/{trialId}/regrade:
+    post:
+      tags: [trials]
+      operationId: regradeTrial
+      summary: Regrade one trial
+      description: |
+        Verifier-only re-run of a single trial. **The response is a Job** — a
+        one-trial regrade job with `source_jobs` recording the provenance.
+        The source trial is immutable. A trial of an UPLOADED job is refused
+        (`job_uploaded`, 409): no recorded verifier inputs exist to re-run.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+      responses:
+        '202':
+          description: The regrade job.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `job_not_terminal`, `no_regradable_trials`, or
+            `regrade_source_ineligible`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/{trialId}/retry:
+    post:
+      tags: [trials]
+      operationId: retryTrial
+      summary: Retry one settled trial
+      description: |
+        Run ONE settled trial again. **The response is a Job** — a one-trial
+        retry job inheriting the source job's config, with `source_jobs`
+        recording `action: "retry"`; view it with `GET /api/jobs/{jobId}`
+        (the 202 carries a `Location` header naming it). The source trial is
+        immutable.
+
+        The same operation as `POST /api/jobs/{jobId}/retry` with
+        `{"trial_ids": [this]}` — one selection rule, one builder, one
+        fingerprint — kept as its own door because the trial page (and
+        Harbor's hosted `trial retry <id>`) address the trial, not the job.
+        The source JOB may still be running: a settled trial's facts are
+        final, so "run it again" is well-defined the moment it settles. A
+        trial of an UPLOADED job is refused (`job_uploaded`, 409).
+
+        Supports `Idempotency-Key` — the identical fingerprint the job-level
+        door computes for this one-trial selection, because it IS the
+        identical request.
+      parameters:
+        - $ref: '#/components/parameters/TrialId'
+        - $ref: '#/components/parameters/IdempotencyKey'
+      responses:
+        '202':
+          description: >
+            The retry job. `Location` names it (`/api/jobs/{jobId}`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '200':
+          description: Idempotent replay of an identical retry request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Job'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '402':
+          description: Out of credits (`insufficient_credits`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            Trial still live (`trial_not_settled` — QUEUED, RUNNING, and
+            SCORING trials cannot be retried), or `idempotency_key_reused`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          description: >
+            Two conditions, distinguished by code: `rate_limited` (the
+            standard throttle — honor `Retry-After`), and `quota_exceeded`
+            — the owning organization's `max_queued_trials` ceiling would
+            be crossed by this job (`details`: `{quota, limit, used,
+            requested, org}`; the message starts `hosted quota exceeded:`).
+            No `Retry-After`: the wait is not a known number. Nothing was
+            created; retry once the organization's queue has drained, or
+            ask the platform administrator to raise the ceiling. A ceiling
+            of 0 means the organization is paused.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/trials/stop:
+    post:
+      tags: [trials]
+      operationId: stopTrials
+      summary: Stop selected running trials or trace analyses
+      description: |
+        Stops individual in-flight trials without cancelling their job: each
+        trial's sandbox is killed and the trial is settled with its spend read
+        from the gateway. Only the caller's own trials; ids belonging to
+        someone else are reported in `not_found` (existence is never leaked).
+        Idempotent — already-terminal trials are reported as such and left
+        untouched.
+
+        Trace-analysis ids ride the same `trial_ids` array — what each id is
+        gets resolved server-side, so a client never partitions a selection.
+        A running analysis has its analyzer box killed and settles `failed`
+        with failure phase `stopped`, its own spend read from the gateway; a
+        queued one settles the same way before any box boots (nothing minted,
+        nothing spent). Stopped analyses come back in `stopped_analyses` with
+        their settled rows; the caller's already-settled analyses land in
+        `already_terminal` and foreign or unknown ids in `not_found` — the
+        trials' refusal semantics, id for id.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/StopRequest'
+      responses:
+        '200':
+          description: Per-trial outcome of the stop request.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/StopResponse'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Analyses — trace-analysis runs as a first-class list
+  # ===========================================================================
+
+  /api/analyses:
+    get:
+      tags: [analyses]
+      operationId: listAnalyses
+      summary: List trace-analysis runs
+      description: |
+        Every trace analysis the caller may read, newest first, cursor-paged.
+        Items are the same `TrialAnalysis` object a trial serves as its
+        LATEST analysis (`Trial.analysis`) — here every analysis answers,
+        earlier waves included, each carrying the trial, job, and task it
+        judged. Harbor has no analysis list (their analyze writes a local
+        `analysis.json` per trial dir); hosted, the analyzer's run is a
+        record of its own and this is its catalog.
+
+        Visibility follows the analyze verb (`POST /api/jobs/{jobId}/analyze`)
+        one relation deeper: an analysis belongs to the analyzed trial's job.
+        `scope=my` (the default) lists analyses of jobs you created;
+        `scope=shared` lists analyses of your organizations' jobs that
+        teammates created. Nothing is public, so Harbor's `all` is refused.
+        An API key sees exactly what its owner may read — there is no
+        wider scope.
+
+        Filters are server-side and compose with the cursor.
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - $ref: '#/components/parameters/ListScope'
+        - name: job
+          in: query
+          description: Only analyses of this job's trials.
+          schema:
+            type: string
+            format: uuid
+        - name: status
+          in: query
+          description: >
+            Filter by the analysis's own lifecycle word (the lowercase
+            ladder `TrialAnalysis.status` speaks) — repeatable and/or
+            comma-separated; an unknown word is refused (`invalid_input`)
+            with the ladder in `details.valid_statuses`.
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [queued, running, completed, failed]
+          explode: true
+      responses:
+        '200':
+          description: One page of analyses.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/AnalysisPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem:
+    get:
+      tags: [analyses]
+      operationId: getAnalysisFilesystem
+      summary: The analysis run's file system — which source it has
+      description: |
+        The Files surface of one analysis run (the file system family, one shape
+        under every run owner: trials, analyses, task checks — and the task
+        package as a fourth, read-only owner). `state` says what the
+        listing, read, search, archive and change routes will answer from:
+        `live` — the box is running and the routes read it as it changes;
+        `captured` — the run ended and its file system was kept, the same
+        routes read the kept tree; `capturing` — the run just ended and the
+        capture is still being written; `none` — nothing to read yet (a
+        queued run, a run older than the feature, a capture that failed —
+        `capture.status` says which). `box` names the running box and its
+        role, `watcher` how change events arrive (`native` from the
+        provider, `poll` from the folders the viewer declared open), and
+        `capture` the kept tree's record: when, after which phase, how many
+        entries and changed files, `ready` | `incomplete` (`left_out` names
+        what did not fit the budget) | `failed`.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+      responses:
+        '200':
+          description: The file system's state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemStatus'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/files:
+    get:
+      tags: [analyses]
+      operationId: listAnalysisFilesystemFolder
+      summary: List one folder of the analysis run's file system
+      description: |
+        One page of a folder, sorted by name, paged with `cursor` (the last
+        name served) and `limit` (default 500, max 1000). `source` forces
+        `live` or `capture`; omitted, whichever the run has (`state` on the
+        status route). Every entry carries its type (`dir` | `file` |
+        `symlink` — with `target` — | `other`), size, mtime, mode and owner;
+        `changed` and `phase` say whether the run created or modified it
+        and in which phase (null when not known for the source); on a
+        captured listing `captured: false` marks a file the run never
+        touched, which only the image holds — it lists but does not open.
+        The kernel trees (`/proc`, `/sys`, `/dev`) are never listed.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the folder.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemListing'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/files/{path}:
+    get:
+      tags: [analyses]
+      operationId: readAnalysisFilesystemFile
+      summary: Read one file of the analysis run's file system, raw bytes
+      description: |
+        RAW BYTES of one file — application/octet-stream, byte fidelity, no
+        translation (whether it is text is the reader's call: the first
+        4 KiB, a NUL byte means binary). A standard single `Range` header
+        (`bytes=a-b`, `bytes=a-`, `bytes=-n`) reads a slice and answers 206
+        with `Content-Range`; `Accept-Ranges: bytes` advertises it; a
+        malformed or multi-range header is the typed 400, an out-of-file
+        range the 416. An unranged read above the deployment's whole-read
+        ceiling is the typed 413 (`invalid_input`, param `Range`, details
+        `size_bytes` / `max_unranged_bytes`) — read it in slices.
+        `X-Source` names the source that answered, `X-Ms` the server time.
+        A symlink reads as its target (one hop). A path the file system
+        does not hold is 404 `not_found`; on a captured read, a file the
+        run never touched is 404 `not_captured` (only the image holds it).
+        A stream that breaks after the headers ends with an aborted
+        connection, never a partial body delivered as success.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - name: path
+          in: path
+          required: true
+          description: The absolute box path, e.g. `app/work/main.py` for `/app/work/main.py` (the leading slash is the route's).
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: Range
+          in: header
+          description: Optional single byte range (`bytes=a-b` / `bytes=a-` / `bytes=-n`).
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The whole file (`X-Source`, `X-Ms`).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '206':
+          description: The requested byte range (`Content-Range` states position and size).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: >
+            An unranged read above the whole-read ceiling (`invalid_input`,
+            param `Range`; details `size_bytes` / `max_unranged_bytes`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '416':
+          description: >
+            Range selects nothing inside the file (`invalid_input`;
+            `Content-Range` carries `bytes */<size>`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/search:
+    get:
+      tags: [analyses]
+      operationId: searchAnalysisFilesystem
+      summary: Search the analysis run's file system for text
+      description: |
+        Content search: `q` is the text (or, with `regex=true`, the
+        pattern), `path` the folder to search under (default `/` — the
+        whole box, `scope: "box"`, which can take seconds; a folder answers
+        `scope: "path"` in well under a second), `limit` the hit cap
+        (default 200, max 1000). `truncated: true` means more hits exist or
+        the search budget ran out — narrow the path or the text. Live: the
+        box is searched as it is; captured: the kept text is searched, and
+        `image_files_excluded: true` says files the run never touched were
+        not searchable. Binary files never hit.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - name: q
+          in: query
+          required: true
+          description: The text to find; a regular expression with `regex=true`.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemPath'
+        - name: regex
+          in: query
+          description: Treat `q` as a regular expression (default false — a plain substring).
+          schema:
+            type: boolean
+            default: false
+        - $ref: '#/components/parameters/FilesystemLimit'
+        - $ref: '#/components/parameters/FilesystemSource'
+      responses:
+        '200':
+          description: The hits found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/events:
+    get:
+      tags: [analyses]
+      operationId: streamAnalysisFilesystemEvents
+      summary: Change events while the analysis run's box lives (SSE)
+      description: |
+        Server-sent events. `event: state` first (`{state, box}`), then
+        `event: fs` per change (`{seq, t, path, type: create|write|remove|
+        rename, source: watch|poll}`, `id: <seq>`), `event: ping` every
+        15 s. Resume with `Last-Event-ID: <seq>` (or `?after=`): the events
+        after it replay when the server still holds them; when it does not,
+        a fresh `state` frame is the signal to relist the open folders.
+        On a provider without a native watcher (`watcher: "poll"` on the
+        status route) events come from polling the folders declared with
+        `POST …/filesystem/watch`, so declare them. A `state` frame follows
+        every change of state; the stream ends once the file system settles
+        (`captured` or `none`).
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume after this event seq.
+          schema:
+            type: string
+        - name: after
+          in: query
+          description: The same as `Last-Event-ID`, for clients that cannot set headers.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/watch:
+    post:
+      tags: [analyses]
+      operationId: watchAnalysisFilesystem
+      summary: Declare the folders the viewer has open
+      description: |
+        The folders whose changes the event stream must report on a
+        provider without a native watcher (`watcher: "poll"`): idempotent —
+        the body's `paths` REPLACES the set; an empty set stops polling. At
+        most 8 folders at once (a bigger set is the typed 400 naming the
+        bound). On a provider with a native watcher the set is accepted
+        and unused. Refused with `filesystem_state` when the box is gone.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/FilesystemWatchRequest'
+      responses:
+        '200':
+          description: The set in force.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemWatchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/changes:
+    get:
+      tags: [analyses]
+      operationId: listAnalysisFilesystemChanges
+      summary: The files the analysis run changed
+      description: |
+        The flat list of what the run created, modified or removed since its
+        box started, with `phase` (`setup` | `agent` | `verifier`); `total`
+        and `changed_bytes` are the whole list's, `items` one page (`cursor`
+        = an opaque position, `limit` default 500, max 1000); `phase=`
+        narrows to one phase. Captured: stored with the kept tree. Live: the
+        box start listing against a fresh one, seconds per call; a box whose
+        start listing was not stored is the typed 422.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: phase
+          in: query
+          description: Only changes of one phase (default all).
+          schema:
+            type: string
+            enum: [setup, agent, verifier, all]
+            default: all
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the changed-files list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemChanges'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — the shape or the provider has no live view
+            of what was asked (details.cause names it).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/filesystem/archive:
+    get:
+      tags: [analyses]
+      operationId: downloadAnalysisFilesystemArchive
+      summary: Download one subtree of the analysis run's file system as a .tar.gz
+      description: |
+        A gzipped tarball of the subtree under `path` (default `/`, the
+        whole tree), streamed. Captured: only the kept bytes ride; the
+        files the run never touched are listed in `MANIFEST.tsv` at the
+        archive root with `captured=false`. Live: read out of the running
+        box under the capture budget — a subtree too large to leave the box
+        inside it is refused up front, 422 `feature_unsupported` with the
+        size in `details.cause`; a read-out that still stalls past the
+        budget aborts the connection, never a truncated archive delivered
+        as success. `X-Source` names the source. A folder the file system
+        does not hold is 404 `not_found`.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+      responses:
+        '200':
+          description: The archive (`Content-Disposition` names it `<id>_filesystem.tar.gz`).
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — the provider has no live view of what was
+            asked, or the live subtree cannot leave the box inside the
+            capture budget (details.cause names it, with the size).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/logs:
+    get:
+      tags: [analyses]
+      operationId: getAnalysisSandboxLog
+      summary: One page of a sandbox log stream of the analysis run
+      description: |
+        The box's own streams, recorded while it runs and kept after:
+        `agent` (the harness's stdout/stderr), `verifier` (the verifier
+        command's) and `system` (the box's system log — only when the job
+        asked for it, `JobCreate.system_log`). `setup` and `metrics` are
+        named but not recorded today. Lines are `{seq, t, fd: out|err, line}`;
+        `cursor` is an opaque position, `limit` default 1000, max 1000. A
+        stream the platform holds nothing for answers an empty page whose
+        `reason` says why — never an error.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - name: stream
+          in: query
+          required: true
+          schema:
+            $ref: '#/components/schemas/SandboxLogStream'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the stream.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SandboxLogLines'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/logs/events:
+    get:
+      tags: [analyses]
+      operationId: streamAnalysisSandboxLogs
+      summary: Sandbox log lines as they arrive (SSE)
+      description: |
+        Server-sent events over every stream at once: `event: line`
+        (`{stream, seq, t, fd, line}`, `id: <stream>:<seq>`), `event: state`
+        on open and on every change of the box's state, `event: ping` every
+        15 s. Without
+        `Last-Event-ID` every stream replays from its beginning and then
+        follows; with `Last-Event-ID: <stream>:<seq>` that stream resumes
+        after the seq the paged GET handed out. Once the box is gone and
+        every recorded line has been sent, the stream ends — the paged GET
+        is the reader after that.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume one stream after `<stream>:<seq>`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/analyses/{analysisId}/procs:
+    get:
+      tags: [analyses]
+      operationId: getAnalysisProcs
+      summary: The analysis run's box process list (live only)
+      description: |
+        The processes running in the box right now, as one text listing
+        (`ps` sorted by memory; on an image without `ps`, the same table
+        read from `/proc`, its first line saying so). Live only: once the
+        box is gone the answer is 409 `filesystem_state`.
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+      responses:
+        '200':
+          description: The listing.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/SandboxProcs'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+
   /api/analyses/{analysisId}/download:
     get:
-      tags: [analyses]
-      operationId: downloadAnalysis
-      summary: Download one analysis run as Harbor's wrapper-trial folder
+      tags: [analyses]
+      operationId: downloadAnalysis
+      summary: Download one analysis run as Harbor's wrapper-trial folder
+      description: |
+        One `.tar.gz` holding the analysis run laid out exactly as the
+        trial directory Harbor's `harbor analyze` leaves on disk for it —
+        the WRAPPER trial (their analyze/analyzer.py assemble_analyze_task
+        wraps one analyzed trial in a generated task named
+        `analyze-<trial dir>` and runs it as a Harbor trial; the folder is
+        that trial's, models/trial/paths.py TrialPaths). The archive
+        extracts to one directory named as Harbor names a trial
+        (`<task name>__<7 chars>`, here `analyze-<analyzed trial dir>__…`):
+
+            analyze-<trial>__<7>/
+            ├── config.json              TrialConfig, partial: the wrapper
+            │                            task's name, the agent (claude-code,
+            │                            the model), and under `x_evolve`
+            │                            the frozen policy — rubric, prompt,
+            │                            reasoning_effort — plus the analyzed
+            │                            trial/job/task and the provider
+            ├── lock.json                TrialLock, partial: the agent and
+            │                            its model (no task digest exists —
+            │                            the wrapper task is never assembled
+            │                            here; see the x_evolve note below)
+            ├── result.json              TrialResult: the wrapper name,
+            │                            agent_info, agent_result (tokens,
+            │                            measured cost), verifier_result
+            │                            (reward 1 = a valid analysis.json,
+            │                            0 = the validator refused it),
+            │                            exception_info on an infrastructure
+            │                            failure, the timings, and under
+            │                            `x_evolve` the run's own facts
+            │                            (status, attempts, the typed failure,
+            │                            the box, the meter, and the task
+            │                            package's fate — `taskContent`
+            │                            retained_package|absent, `taskAbsentReason`
+            │                            when absent)
+            ├── trial.log                the worker's phase log, rendered
+            │                            deterministically (the trial tree's
+            │                            own renderer)
+            ├── exception.txt            when the run failed OUTSIDE the
+            │                            validator (an infrastructure phase)
+            ├── agent/
+            │   ├── claude-code.txt      the analyzer's stdout stream at
+            │   │                        Harbor's own tee name for claude-code
+            │   ├── stderr.log           its stderr, when stored
+            │   ├── trace-parsed.jsonl   the run's parsed event trace
+            │   ├── .claude/ …           the captured home at its real names,
+            │   ├── agent-home.json      the capture record beside it
+            │   └── sessions/ …          Harbor's own copy of the .claude/
+            │                            subtree (claude_code.py:482)
+            ├── verifier/                ONLY when the validator ruled —
+            │   │                        completed, or failed `invalid_result`
+            │   ├── test-stdout.txt      the validator's printed reasons
+            │   │                        (empty on a valid result, as
+            │   │                        Harbor's validate.py prints nothing)
+            │   ├── reward.txt           `1` or `0` — the exact bytes Harbor's
+            │   │                        wrapper test.sh writes
+            │   └── reward.json          {"reward": 1|0}
+            └── artifacts/
+                ├── manifest.json        always present — what was collected
+                │                        (`[]` when the run produced nothing)
+                └── analysis.json        the validated deliverable — summary
+                                         + checks — only on a completed run
+
+        The validator runs on the platform's worker, not inside the box
+        (a recorded deviation: the rule is the platform's one result
+        definition, which the box's validate.py records; the reasons are that
+        definition's issues, one per line as `path: message`); the run's raw
+        deliverable is not retained, so
+        `artifacts/analysis.json` is the validated document in canonical
+        JSON and a refused deliverable leaves no file. The image digest and
+        the harness bundle version resolve per run but are not stored on
+        the row, so `lock.json` cannot state them (capture-side, deferred).
+        Data the platform does not hold is left out, never faked.
+
+        Deterministic: re-downloads are byte-identical (stored rows only,
+        canonical JSON, fixed tar mtimes, zero gzip mtime). Readable by the
+        analyzed job's creator and the owning organization's members;
+        anyone else gets 404 `analysis_not_found`, indistinguishable from
+        an id that does not exist. A run still queued or running refuses
+        409 `analysis_not_terminal` — the folder is a record of a settled
+        run.
+
+        `evolve analysis download <analysis-id>` extracts it and adds
+        `evolve.json` (the platform record Harbor's layout has no slot for).
+      parameters:
+        - $ref: '#/components/parameters/AnalysisId'
+      responses:
+        '200':
+          description: The archive.
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: The analysis is still queued or running (`analysis_not_terminal`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  # ===========================================================================
+  # Checks — task quality checks (Harbor's `harbor check`, hosted)
+  # ===========================================================================
+
+  /api/checks:
+    post:
+      tags: [checks]
+      operationId: createCheck
+      summary: Check task quality against a rubric (Harbor's `harbor check`)
+      description: |
+        Harbor's `harbor check <PATH>` (their cli/analyze.py:84-207
+        check_command; analyze/checker.py run_checks), hosted: PATH — one
+        task directory, or a directory of task directories — arrives as a
+        gzipped tarball (`archive`), or a published dataset is named
+        instead (`dataset`, the hosted form; `CheckRequest.dataset` states
+        the deviation and its reason), and for each task directory it holds
+        the checker agent (claude-code, Harbor's own check agent, in its own
+        sandbox, under the network Harbor's check wrapper task gives it —
+        open by default) reads EVERY file of the task and rules every rubric
+        criterion `pass`, `fail`, `not_applicable` or `unknown` with a
+        rationale and the evidence behind it, writing `check-result.json`
+        (the platform's default check prompt and rubric, rendered through
+        Harbor's own tokens and join; `prompt` and `rubric` replace them).
+        **The response is the Check**
+        (202): the record with one `results` entry per task, each `queued`
+        — poll `GET /api/checks/{checkId}` to watch them settle (the
+        `status` of the check reads `completed` once every task has).
+
+        Which task directories, exactly as Harbor decides it
+        (checker.py:116-141 over the archive's listing): the archive root
+        when it is a task directory (task.toml + environment/ +
+        instruction.md + the test script of its `[environment].os` —
+        tests/test.sh for linux, the default; tests/test.bat for windows;
+        a `[[steps]]` task needs each step's instruction.md and its own or
+        the shared test script — their Task.is_valid_dir), else every
+        top-level directory that is one, sorted; then the
+        `include_task_names` globs (any match keeps), the
+        `exclude_task_names` globs (any match drops), then the first
+        `n_tasks`. An empty selection is refused `no_checkable_tasks`
+        (their "No valid task directories found", :140); nothing is stored.
+        There is no task-count ceiling — Harbor's check has none (no
+        invented number, owner 2026-09-13); the organization's
+        `max_concurrent_analyses` paces the boxes. On the dataset form the
+        same selection runs over the version's task names, and the same
+        refusal answers. The `config`
+        part is the JSON `CheckConfigInput`; absent or
+        `{}` means the defaults (openrouter/deepseek/deepseek-v4.1-flash at its
+        per-model effort, the platform's default check rubric — eleven
+        criteria, `CheckConfigInput.rubric` names them).
+
+        The task bytes are never modified and never land anywhere but the
+        checker's sandbox and the platform's rows: Harbor's own rule ("Do
+        not modify any files under {task_path}"; nothing written into the
+        reviewed directory — their report is the job dir's
+        check_report.json). A checker run that completes without a valid
+        `check-result.json` is automatically re-run at most once (fresh
+        sandbox, same model and rubric; the task's `attempts` says how far
+        the ladder went), the analyze verb's own hosted rule; a run cut by
+        its budget settles `failed` with phase `timeout` at once and is
+        never re-run.
+
+        Decision order: 400 `invalid_multipart` (not multipart, or a
+        malformed body) → 413 `upload_too_large` (the archive over what the
+        store can land or what the server's spool disk has free — both read
+        live at the request, the refusal naming which; no platform number)
+        → 429
+        `too_many_concurrent_check_uploads` (the server's spool bound,
+        ruled at the archive part before its first byte) → 400
+        `invalid_rubric` / `invalid_input` (the `config` part: the rubric
+        grammar; then an off-roster model, a bad `prompt`, an off-lineup
+        `sandbox_provider`, an off-vocabulary `reasoning_effort`, an
+        out-of-range `n_concurrent`, a malformed glob list, an invalid
+        `n_tasks` — in that order, the analyze door's own ladder under the
+        `check.` prefix) → 400 `invalid_input` (both `archive` and `dataset`,
+        or neither) → the dataset form's resolution refusals
+        (`CheckRequest.dataset`) → 400 `invalid_archive` (not a readable gzipped
+        tar, an unsafe entry, or a listing that would hold more heap than
+        the server can still commit — read live, named in the refusal) →
+        400 `no_checkable_tasks` → 202.
+      requestBody:
+        required: true
+        content:
+          multipart/form-data:
+            schema:
+              $ref: '#/components/schemas/CheckRequest'
+      responses:
+        '202':
+          description: The check, its task checks queued.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Check'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '413':
+          description: The archive is over the physical ceiling read at the request — the store's, or the spool disk's (`upload_too_large`; details.max_bytes and details.source).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          description: >
+            Two conditions, distinguished by code: `rate_limited` (the
+            standard throttle — honor `Retry-After`), and
+            `too_many_concurrent_check_uploads` — the server is already
+            spooling its bound of concurrent check archives
+            (`max_concurrent` in the details), refused before the first
+            uploaded byte, with no `Retry-After` because the server cannot
+            honestly compute one; retry when an in-flight upload finishes.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '500':
+          $ref: '#/components/responses/InternalError'
+    get:
+      tags: [checks]
+      operationId: listChecks
+      summary: List task quality checks
       description: |
-        One `.tar.gz` holding the analysis run laid out exactly as the
-        trial directory Harbor's `harbor analyze` leaves on disk for it —
-        the WRAPPER trial (their analyze/analyzer.py assemble_analyze_task
-        wraps one analyzed trial in a generated task named
-        `analyze-<trial dir>` and runs it as a Harbor trial; the folder is
-        that trial's, models/trial/paths.py TrialPaths). The archive
-        extracts to one directory named as Harbor names a trial
-        (`<task name>__<7 chars>`, here `analyze-<analyzed trial dir>__…`):
+        Every check the caller may read, newest first, cursor-paged — each
+        item the full `Check` with its per-task results. Harbor has no
+        check list (their check writes a local report per invocation);
+        hosted, the run is a record of its own and this is its catalog.
+        `scope=my` (the default) lists checks you created; `scope=shared`
+        lists your organizations' checks that teammates created (the
+        analyses list's own law, on the check's own org). Nothing is
+        public, so Harbor's `all` is refused. `status` filters by the
+        check's own ladder (`queued`, `running`, `completed`), repeatable
+        and/or comma-separated; an unknown word is refused
+        `invalid_input` with the ladder in `details.valid_statuses`.
+        `dataset` narrows to the checks of one published dataset (the
+        dataset form's `source.dataset`): `name` spans every version of
+        it, `name@version` is one version — the spelling `CheckRequest.
+        dataset` takes. Archive checks never match. A dataset the caller
+        has no checks of is an ordinary empty page; a malformed value
+        (an empty half around the `@`) is refused `invalid_input` on
+        `dataset`.
+      parameters:
+        - $ref: '#/components/parameters/Limit'
+        - $ref: '#/components/parameters/Cursor'
+        - $ref: '#/components/parameters/ListScope'
+        - name: status
+          in: query
+          schema:
+            type: array
+            items:
+              type: string
+              enum: [queued, running, completed]
+          explode: true
+        - name: dataset
+          in: query
+          description: >
+            Only checks of this published dataset — `name` (every version)
+            or `name@version` (one version), exact on the check's
+            `source.dataset`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: One page of checks.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CheckPage'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-            analyze-<trial>__<7>/
-            ├── config.json              TrialConfig, partial: the wrapper
-            │                            task's name, the agent (claude-code,
-            │                            the model), and under `x_evolve`
-            │                            the frozen policy — rubric, prompt,
-            │                            reasoning_effort — plus the analyzed
-            │                            trial/job/task and the provider
-            ├── lock.json                TrialLock, partial: the agent and
-            │                            its model (no task digest exists —
-            │                            the wrapper task is never assembled
-            │                            here; see the x_evolve note below)
-            ├── result.json              TrialResult: the wrapper name,
-            │                            agent_info, agent_result (tokens,
-            │                            measured cost), verifier_result
-            │                            (reward 1 = a valid analysis.json,
-            │                            0 = the validator refused it),
-            │                            exception_info on an infrastructure
-            │                            failure, the timings, and under
-            │                            `x_evolve` the run's own facts
-            │                            (status, attempts, the typed failure,
-            │                            the box, the meter, and the task
-            │                            package's fate — `taskContent`
-            │                            retained_package|absent, `taskAbsentReason`
-            │                            when absent)
-            ├── trial.log                the worker's phase log, rendered
-            │                            deterministically (the trial tree's
-            │                            own renderer)
-            ├── exception.txt            when the run failed OUTSIDE the
-            │                            validator (an infrastructure phase)
-            ├── agent/
-            │   ├── claude-code.txt      the analyzer's stdout stream at
-            │   │                        Harbor's own tee name for claude-code
-            │   ├── stderr.log           its stderr, when stored
-            │   ├── trace-parsed.jsonl   the run's parsed event trace
-            │   ├── .claude/ …           the captured home at its real names,
-            │   ├── agent-home.json      the capture record beside it
-            │   └── sessions/ …          Harbor's own copy of the .claude/
-            │                            subtree (claude_code.py:482)
-            ├── verifier/                ONLY when the validator ruled —
-            │   │                        completed, or failed `invalid_result`
-            │   ├── test-stdout.txt      the validator's printed reasons
-            │   │                        (empty on a valid result, as
-            │   │                        Harbor's validate.py prints nothing)
-            │   ├── reward.txt           `1` or `0` — the exact bytes Harbor's
-            │   │                        wrapper test.sh writes
-            │   └── reward.json          {"reward": 1|0}
-            └── artifacts/
-                ├── manifest.json        always present — what was collected
-                │                        (`[]` when the run produced nothing)
-                └── analysis.json        the validated deliverable — summary
-                                         + checks — only on a completed run
+  /api/checks/defaults:
+    get:
+      tags: [checks]
+      operationId: getCheckDefaults
+      summary: The defaults a check runs under when its config names nothing
+      description: |
+        The resolved policy an empty `CheckConfigInput` falls back to — the
+        five knobs the create door stamps on every check that names none:
+        `model_name`, `rubric` (the platform's check rubric, the eleven
+        criteria `CheckConfigInput` lists), `prompt` (the built-in check
+        body, as the TEMPLATE a caller's own `prompt` replaces — with its
+        `{task_path}`, `{file_tree}` and `{criteria_guidance}` slots
+        unrendered; the output section Harbor appends is not part of it),
+        `reasoning_effort` (the default model's per-model effort) and
+        `sandbox_provider` (the fleet default). Read them to see what a
+        bare `evolve check` runs under, or to start an edited rubric or
+        prompt from the platform's own. `model_name` and `rubric` sent
+        back resolve as if nothing was sent; `prompt`, `reasoning_effort`
+        and `sandbox_provider` sent back are stored as named, so the check
+        echoes the prompt text and keeps that effort and provider even
+        when the fleet default later changes. Harbor
+        has no such verb: its defaults are files on disk
+        (cli/quality_checker/default-rubric.toml, analyze/prompts/
+        check.txt), which a hosted caller cannot open — the hosted reading
+        of the same files.
+      responses:
+        '200':
+          description: The resolved defaults.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/CheckDefaults'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-        The validator runs on the platform's worker, not inside the box
-        (a recorded deviation: the rule is the platform's one result
-        definition, which the box's validate.py records; the reasons are that
-        definition's issues, one per line as `path: message`); the run's raw
-        deliverable is not retained, so
-        `artifacts/analysis.json` is the validated document in canonical
-        JSON and a refused deliverable leaves no file. The image digest and
-        the harness bundle version resolve per run but are not stored on
-        the row, so `lock.json` cannot state them (capture-side, deferred).
-        Data the platform does not hold is left out, never faked.
+  /api/checks/{checkId}:
+    get:
+      tags: [checks]
+      operationId: getCheck
+      summary: Get one task quality check (the report)
+      description: |
+        The check with its per-task results — Harbor's CheckReport
+        (`results`, their cli/quality_checker/models.py:38-41) plus the
+        policy it ran under and its source. Readable by the creator and by
+        every member of the owning organization; anyone else gets 404
+        `check_not_found`, indistinguishable from an id that does not exist.
 
-        Deterministic: re-downloads are byte-identical (stored rows only,
-        canonical JSON, fixed tar mtimes, zero gzip mtime). Readable by the
-        analyzed job's creator and the owning organization's members;
-        anyone else gets 404 `analysis_not_found`, indistinguishable from
-        an id that does not exist. A run still queued or running refuses
-        409 `analysis_not_terminal` — the folder is a record of a settled
-        run.
+        Each task's result (`results[].id`) is also a run of its own, read
+        exactly like an analysis run (owner ruling 2026-09-09): the
+        checker's live trace, raw streams, agent home and its result file
+        (`check-result.json`, Harbor's name for the checker's deliverable —
+        checker.py:37) are served by the traces feed's per-run doors under
+        the task check's id — the doors `evolve check trace` and `evolve
+        check download` ride — under the check's own access law (creator or
+        org member). A task check is stoppable there too (the feed's stop
+        verb), one task at a time.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+      responses:
+        '200':
+          description: The check.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Check'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem:
+    get:
+      tags: [checks]
+      operationId: getTaskCheckFilesystem
+      summary: The task check's file system — which source it has
+      description: |
+        The Files surface of one task check (the file system family, one shape
+        under every run owner: trials, analyses, task checks — and the task
+        package as a fourth, read-only owner). `state` says what the
+        listing, read, search, archive and change routes will answer from:
+        `live` — the box is running and the routes read it as it changes;
+        `captured` — the run ended and its file system was kept, the same
+        routes read the kept tree; `capturing` — the run just ended and the
+        capture is still being written; `none` — nothing to read yet (a
+        queued run, a run older than the feature, a capture that failed —
+        `capture.status` says which). `box` names the running box and its
+        role, `watcher` how change events arrive (`native` from the
+        provider, `poll` from the folders the viewer declared open), and
+        `capture` the kept tree's record: when, after which phase, how many
+        entries and changed files, `ready` | `incomplete` (`left_out` names
+        what did not fit the budget) | `failed`.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+      responses:
+        '200':
+          description: The file system's state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemStatus'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/files:
+    get:
+      tags: [checks]
+      operationId: listTaskCheckFilesystemFolder
+      summary: List one folder of the task check's file system
+      description: |
+        One page of a folder, sorted by name, paged with `cursor` (the last
+        name served) and `limit` (default 500, max 1000). `source` forces
+        `live` or `capture`; omitted, whichever the run has (`state` on the
+        status route). Every entry carries its type (`dir` | `file` |
+        `symlink` — with `target` — | `other`), size, mtime, mode and owner;
+        `changed` and `phase` say whether the run created or modified it
+        and in which phase (null when not known for the source); on a
+        captured listing `captured: false` marks a file the run never
+        touched, which only the image holds — it lists but does not open.
+        The kernel trees (`/proc`, `/sys`, `/dev`) are never listed.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the folder.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemListing'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-        `evolve analysis download <analysis-id>` extracts it and adds
-        `evolve.json` (the platform record Harbor's layout has no slot for).
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/files/{path}:
+    get:
+      tags: [checks]
+      operationId: readTaskCheckFilesystemFile
+      summary: Read one file of the task check's file system, raw bytes
+      description: |
+        RAW BYTES of one file — application/octet-stream, byte fidelity, no
+        translation (whether it is text is the reader's call: the first
+        4 KiB, a NUL byte means binary). A standard single `Range` header
+        (`bytes=a-b`, `bytes=a-`, `bytes=-n`) reads a slice and answers 206
+        with `Content-Range`; `Accept-Ranges: bytes` advertises it; a
+        malformed or multi-range header is the typed 400, an out-of-file
+        range the 416. An unranged read above the deployment's whole-read
+        ceiling is the typed 413 (`invalid_input`, param `Range`, details
+        `size_bytes` / `max_unranged_bytes`) — read it in slices.
+        `X-Source` names the source that answered, `X-Ms` the server time.
+        A symlink reads as its target (one hop). A path the file system
+        does not hold is 404 `not_found`; on a captured read, a file the
+        run never touched is 404 `not_captured` (only the image holds it).
+        A stream that breaks after the headers ends with an aborted
+        connection, never a partial body delivered as success.
       parameters:
-        - $ref: '#/components/parameters/AnalysisId'
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - name: path
+          in: path
+          required: true
+          description: The absolute box path, e.g. `app/work/main.py` for `/app/work/main.py` (the leading slash is the route's).
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: Range
+          in: header
+          description: Optional single byte range (`bytes=a-b` / `bytes=a-` / `bytes=-n`).
+          schema:
+            type: string
       responses:
         '200':
-          description: The archive.
+          description: The whole file (`X-Source`, `X-Ms`).
           content:
-            application/gzip:
+            application/octet-stream:
               schema:
                 type: string
                 format: binary
+        '206':
+          description: The requested byte range (`Content-Range` states position and size).
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
         '409':
-          description: The analysis is still queued or running (`analysis_not_terminal`).
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
+          description: >
+            An unranged read above the whole-read ceiling (`invalid_input`,
+            param `Range`; details `size_bytes` / `max_unranged_bytes`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '416':
+          description: >
+            Range selects nothing inside the file (`invalid_input`;
+            `Content-Range` carries `bytes */<size>`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
           content:
             application/json:
               schema:
@@ -2667,206 +4461,467 @@ paths:
         '500':
           $ref: '#/components/responses/InternalError'
 
-  # ===========================================================================
-  # Checks — task quality checks (Harbor's `harbor check`, hosted)
-  # ===========================================================================
-
-  /api/checks:
-    post:
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/search:
+    get:
       tags: [checks]
-      operationId: createCheck
-      summary: Check task quality against a rubric (Harbor's `harbor check`)
+      operationId: searchTaskCheckFilesystem
+      summary: Search the task check's file system for text
       description: |
-        Harbor's `harbor check <PATH>` (their cli/analyze.py:84-207
-        check_command; analyze/checker.py run_checks), hosted: PATH — one
-        task directory, or a directory of task directories — arrives as a
-        gzipped tarball (`archive`), or a published dataset is named
-        instead (`dataset`, the hosted form; `CheckRequest.dataset` states
-        the deviation and its reason), and for each task directory it holds
-        the checker agent (claude-code, Harbor's own check agent, in its own
-        sandbox, under the network Harbor's check wrapper task gives it —
-        open by default) reads EVERY file of the task and rules every rubric
-        criterion `pass`, `fail`, `not_applicable` or `unknown` with a
-        rationale and the evidence behind it, writing `check-result.json`
-        (the platform's default check prompt and rubric, rendered through
-        Harbor's own tokens and join; `prompt` and `rubric` replace them).
-        **The response is the Check**
-        (202): the record with one `results` entry per task, each `queued`
-        — poll `GET /api/checks/{checkId}` to watch them settle (the
-        `status` of the check reads `completed` once every task has).
-
-        Which task directories, exactly as Harbor decides it
-        (checker.py:116-141 over the archive's listing): the archive root
-        when it is a task directory (task.toml + environment/ +
-        instruction.md + the test script of its `[environment].os` —
-        tests/test.sh for linux, the default; tests/test.bat for windows;
-        a `[[steps]]` task needs each step's instruction.md and its own or
-        the shared test script — their Task.is_valid_dir), else every
-        top-level directory that is one, sorted; then the
-        `include_task_names` globs (any match keeps), the
-        `exclude_task_names` globs (any match drops), then the first
-        `n_tasks`. An empty selection is refused `no_checkable_tasks`
-        (their "No valid task directories found", :140); nothing is stored.
-        There is no task-count ceiling — Harbor's check has none (no
-        invented number, owner 2026-09-13); the organization's
-        `max_concurrent_analyses` paces the boxes. On the dataset form the
-        same selection runs over the version's task names, and the same
-        refusal answers. The `config`
-        part is the JSON `CheckConfigInput`; absent or
-        `{}` means the defaults (openrouter/deepseek/deepseek-v4.1-flash at its
-        per-model effort, the platform's default check rubric — eleven
-        criteria, `CheckConfigInput.rubric` names them).
+        Content search: `q` is the text (or, with `regex=true`, the
+        pattern), `path` the folder to search under (default `/` — the
+        whole box, `scope: "box"`, which can take seconds; a folder answers
+        `scope: "path"` in well under a second), `limit` the hit cap
+        (default 200, max 1000). `truncated: true` means more hits exist or
+        the search budget ran out — narrow the path or the text. Live: the
+        box is searched as it is; captured: the kept text is searched, and
+        `image_files_excluded: true` says files the run never touched were
+        not searchable. Binary files never hit.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - name: q
+          in: query
+          required: true
+          description: The text to find; a regular expression with `regex=true`.
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemPath'
+        - name: regex
+          in: query
+          description: Treat `q` as a regular expression (default false — a plain substring).
+          schema:
+            type: boolean
+            default: false
+        - $ref: '#/components/parameters/FilesystemLimit'
+        - $ref: '#/components/parameters/FilesystemSource'
+      responses:
+        '200':
+          description: The hits found.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemSearchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-        The task bytes are never modified and never land anywhere but the
-        checker's sandbox and the platform's rows: Harbor's own rule ("Do
-        not modify any files under {task_path}"; nothing written into the
-        reviewed directory — their report is the job dir's
-        check_report.json). A checker run that completes without a valid
-        `check-result.json` is automatically re-run at most once (fresh
-        sandbox, same model and rubric; the task's `attempts` says how far
-        the ladder went), the analyze verb's own hosted rule; a run cut by
-        its budget settles `failed` with phase `timeout` at once and is
-        never re-run.
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/events:
+    get:
+      tags: [checks]
+      operationId: streamTaskCheckFilesystemEvents
+      summary: Change events while the task check's box lives (SSE)
+      description: |
+        Server-sent events. `event: state` first (`{state, box}`), then
+        `event: fs` per change (`{seq, t, path, type: create|write|remove|
+        rename, source: watch|poll}`, `id: <seq>`), `event: ping` every
+        15 s. Resume with `Last-Event-ID: <seq>` (or `?after=`): the events
+        after it replay when the server still holds them; when it does not,
+        a fresh `state` frame is the signal to relist the open folders.
+        On a provider without a native watcher (`watcher: "poll"` on the
+        status route) events come from polling the folders declared with
+        `POST …/filesystem/watch`, so declare them. A `state` frame follows
+        every change of state; the stream ends once the file system settles
+        (`captured` or `none`).
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume after this event seq.
+          schema:
+            type: string
+        - name: after
+          in: query
+          description: The same as `Last-Event-ID`, for clients that cannot set headers.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-        Decision order: 400 `invalid_multipart` (not multipart, or a
-        malformed body) → 413 `upload_too_large` (the archive over what the
-        store can land or what the server's spool disk has free — both read
-        live at the request, the refusal naming which; no platform number)
-        → 429
-        `too_many_concurrent_check_uploads` (the server's spool bound,
-        ruled at the archive part before its first byte) → 400
-        `invalid_rubric` / `invalid_input` (the `config` part: the rubric
-        grammar; then an off-roster model, a bad `prompt`, an off-lineup
-        `sandbox_provider`, an off-vocabulary `reasoning_effort`, an
-        out-of-range `n_concurrent`, a malformed glob list, an invalid
-        `n_tasks` — in that order, the analyze door's own ladder under the
-        `check.` prefix) → 400 `invalid_input` (both `archive` and `dataset`,
-        or neither) → the dataset form's resolution refusals
-        (`CheckRequest.dataset`) → 400 `invalid_archive` (not a readable gzipped
-        tar, an unsafe entry, or a listing that would hold more heap than
-        the server can still commit — read live, named in the refusal) →
-        400 `no_checkable_tasks` → 202.
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/watch:
+    post:
+      tags: [checks]
+      operationId: watchTaskCheckFilesystem
+      summary: Declare the folders the viewer has open
+      description: |
+        The folders whose changes the event stream must report on a
+        provider without a native watcher (`watcher: "poll"`): idempotent —
+        the body's `paths` REPLACES the set; an empty set stops polling. At
+        most 8 folders at once (a bigger set is the typed 400 naming the
+        bound). On a provider with a native watcher the set is accepted
+        and unused. Refused with `filesystem_state` when the box is gone.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
       requestBody:
         required: true
         content:
-          multipart/form-data:
+          application/json:
             schema:
-              $ref: '#/components/schemas/CheckRequest'
+              $ref: '#/components/schemas/FilesystemWatchRequest'
       responses:
-        '202':
-          description: The check, its task checks queued.
+        '200':
+          description: The set in force.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemWatchResult'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/changes:
+    get:
+      tags: [checks]
+      operationId: listTaskCheckFilesystemChanges
+      summary: The files the task check changed
+      description: |
+        The flat list of what the run created, modified or removed since its
+        box started, with `phase` (`setup` | `agent` | `verifier`); `total`
+        and `changed_bytes` are the whole list's, `items` one page (`cursor`
+        = an opaque position, `limit` default 500, max 1000); `phase=`
+        narrows to one phase. Captured: stored with the kept tree. Live: the
+        box start listing against a fresh one, seconds per call; a box whose
+        start listing was not stored is the typed 422.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - $ref: '#/components/parameters/FilesystemSource'
+        - name: phase
+          in: query
+          description: Only changes of one phase (default all).
+          schema:
+            type: string
+            enum: [setup, agent, verifier, all]
+            default: all
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the changed-files list.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemChanges'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Check'
+                $ref: '#/components/schemas/Error'
+        '422':
+          description: >
+            `feature_unsupported` — the shape or the provider has no live view
+            of what was asked (details.cause names it).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/checks/{checkId}/tasks/{taskCheckId}/filesystem/archive:
+    get:
+      tags: [checks]
+      operationId: downloadTaskCheckFilesystemArchive
+      summary: Download one subtree of the task check's file system as a .tar.gz
+      description: |
+        A gzipped tarball of the subtree under `path` (default `/`, the
+        whole tree), streamed. Captured: only the kept bytes ride; the
+        files the run never touched are listed in `MANIFEST.tsv` at the
+        archive root with `captured=false`. Live: read out of the running
+        box under the capture budget — a subtree too large to leave the box
+        inside it is refused up front, 422 `feature_unsupported` with the
+        size in `details.cause`; a read-out that still stalls past the
+        budget aborts the connection, never a truncated archive delivered
+        as success. `X-Source` names the source. A folder the file system
+        does not hold is 404 `not_found`.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemSource'
+      responses:
+        '200':
+          description: The archive (`Content-Disposition` names it `<id>_filesystem.tar.gz`).
+          content:
+            application/gzip:
+              schema:
+                type: string
+                format: binary
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
-        '413':
-          description: The archive is over the physical ceiling read at the request — the store's, or the spool disk's (`upload_too_large`; details.max_bytes and details.source).
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
-        '429':
+        '422':
           description: >
-            Two conditions, distinguished by code: `rate_limited` (the
-            standard throttle — honor `Retry-After`), and
-            `too_many_concurrent_check_uploads` — the server is already
-            spooling its bound of concurrent check archives
-            (`max_concurrent` in the details), refused before the first
-            uploaded byte, with no `Retry-After` because the server cannot
-            honestly compute one; retry when an in-flight upload finishes.
+            `feature_unsupported` — the provider has no live view of what was
+            asked, or the live subtree cannot leave the box inside the
+            capture budget (details.cause names it, with the size).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
           content:
             application/json:
               schema:
                 $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
+
+  /api/checks/{checkId}/tasks/{taskCheckId}/logs:
     get:
       tags: [checks]
-      operationId: listChecks
-      summary: List task quality checks
+      operationId: getTaskCheckSandboxLog
+      summary: One page of a sandbox log stream of the task check
       description: |
-        Every check the caller may read, newest first, cursor-paged — each
-        item the full `Check` with its per-task results. Harbor has no
-        check list (their check writes a local report per invocation);
-        hosted, the run is a record of its own and this is its catalog.
-        `scope=my` (the default) lists checks you created; `scope=shared`
-        lists your organizations' checks that teammates created (the
-        analyses list's own law, on the check's own org). Nothing is
-        public, so Harbor's `all` is refused. `status` filters by the
-        check's own ladder (`queued`, `running`, `completed`), repeatable
-        and/or comma-separated; an unknown word is refused
-        `invalid_input` with the ladder in `details.valid_statuses`.
+        The box's own streams, recorded while it runs and kept after:
+        `agent` (the harness's stdout/stderr), `verifier` (the verifier
+        command's) and `system` (the box's system log — only when the job
+        asked for it, `JobCreate.system_log`). `setup` and `metrics` are
+        named but not recorded today. Lines are `{seq, t, fd: out|err, line}`;
+        `cursor` is an opaque position, `limit` default 1000, max 1000. A
+        stream the platform holds nothing for answers an empty page whose
+        `reason` says why — never an error.
       parameters:
-        - $ref: '#/components/parameters/Limit'
-        - $ref: '#/components/parameters/Cursor'
-        - $ref: '#/components/parameters/ListScope'
-        - name: status
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - name: stream
           in: query
+          required: true
           schema:
-            type: array
-            items:
-              type: string
-              enum: [queued, running, completed]
-          explode: true
+            $ref: '#/components/schemas/SandboxLogStream'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
       responses:
         '200':
-          description: One page of checks.
+          description: One page of the stream.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/CheckPage'
+                $ref: '#/components/schemas/SandboxLogLines'
         '400':
           $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '429':
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
 
-  /api/checks/{checkId}:
+  /api/checks/{checkId}/tasks/{taskCheckId}/logs/events:
     get:
       tags: [checks]
-      operationId: getCheck
-      summary: Get one task quality check (the report)
+      operationId: streamTaskCheckSandboxLogs
+      summary: Sandbox log lines as they arrive (SSE)
       description: |
-        The check with its per-task results — Harbor's CheckReport
-        (`results`, their cli/quality_checker/models.py:38-41) plus the
-        policy it ran under and its source. Readable by the creator and by
-        every member of the owning organization; anyone else gets 404
-        `check_not_found`, indistinguishable from an id that does not exist.
+        Server-sent events over every stream at once: `event: line`
+        (`{stream, seq, t, fd, line}`, `id: <stream>:<seq>`), `event: state`
+        on open and on every change of the box's state, `event: ping` every
+        15 s. Without
+        `Last-Event-ID` every stream replays from its beginning and then
+        follows; with `Last-Event-ID: <stream>:<seq>` that stream resumes
+        after the seq the paged GET handed out. Once the box is gone and
+        every recorded line has been sent, the stream ends — the paged GET
+        is the reader after that.
+      parameters:
+        - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
+        - name: Last-Event-ID
+          in: header
+          description: Resume one stream after `<stream>:<seq>`.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The event stream.
+          content:
+            text/event-stream:
+              schema:
+                type: string
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
 
-        Each task's result (`results[].id`) is also a run of its own, read
-        exactly like an analysis run (owner ruling 2026-09-09): the
-        checker's live trace, raw streams, agent home and its result file
-        (`check-result.json`, Harbor's name for the checker's deliverable —
-        checker.py:37) are served by the traces feed's per-run doors under
-        the task check's id — the doors `evolve check trace` and `evolve
-        check download` ride — under the check's own access law (creator or
-        org member). A task check is stoppable there too (the feed's stop
-        verb), one task at a time.
+  /api/checks/{checkId}/tasks/{taskCheckId}/procs:
+    get:
+      tags: [checks]
+      operationId: getTaskCheckProcs
+      summary: The task check's box process list (live only)
+      description: |
+        The processes running in the box right now, as one text listing
+        (`ps` sorted by memory; on an image without `ps`, the same table
+        read from `/proc`, its first line saying so). Live only: once the
+        box is gone the answer is 409 `filesystem_state`.
       parameters:
         - $ref: '#/components/parameters/CheckId'
+        - $ref: '#/components/parameters/TaskCheckId'
       responses:
         '200':
-          description: The check.
+          description: The listing.
           content:
             application/json:
               schema:
-                $ref: '#/components/schemas/Check'
+                $ref: '#/components/schemas/SandboxProcs'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '404':
           $ref: '#/components/responses/NotFound'
+        '409':
+          description: >
+            `filesystem_state` — `source=live` while the box is gone, or
+            `source=capture` before a capture exists (details carry the
+            requested source and the state).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '503':
+          description: >
+            `provider_unreachable` — the box's provider did not answer;
+            retry after `Retry-After`.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
         '429':
           $ref: '#/components/responses/TooManyRequests'
         '500':
           $ref: '#/components/responses/InternalError'
 
+
   /api/checks/{checkId}/download:
     get:
       tags: [checks]
@@ -3410,25 +5465,200 @@ paths:
           required: true
           schema:
             type: string
-        - name: task_name
+        - name: task_name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The task's build outcome.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaskBuild'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          description: >
+            `dataset_not_found`, `dataset_version_not_found`, or
+            `task_not_found` (no build outcome recorded under that name in
+            this version).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}/versions/{version}/tasks/{task_name}/filesystem:
+    get:
+      tags: [datasets]
+      operationId: getTaskPackageFilesystem
+      summary: The task package as a file system (status)
+      description: |
+        The task directory's files as the fourth, read-only owner of the
+        file system family: served from the retained task package — the
+        exact bytes the import stored, the ones every trial ran against.
+        `state` is always `none` (no box, no capture), `source` is
+        `package`; `package_retained` says whether the version keeps its
+        package — one imported before packages were retained answers the
+        listing and read with 409 `task_package_not_retained`. No events,
+        no logs, no search beyond the path filter.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: task_name
+          in: path
+          required: true
+          schema:
+            type: string
+      responses:
+        '200':
+          description: The package owner's state.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/TaskPackageFilesystemStatus'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}/versions/{version}/tasks/{task_name}/filesystem/files:
+    get:
+      tags: [datasets]
+      operationId: listTaskPackageFolder
+      summary: List one folder of the task package
+      description: |
+        The same page as a run's folder listing (`FilesystemListing`), over
+        the task directory (`/` is the directory holding instruction.md,
+        task.toml, environment/, tests/); `source` may only be `package`.
+        Every file is held (`captured: true`); `changed` and `phase` are
+        null. A version that keeps no package is 409
+        `task_package_not_retained`.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: task_name
+          in: path
+          required: true
+          schema:
+            type: string
+        - $ref: '#/components/parameters/FilesystemPath'
+        - $ref: '#/components/parameters/FilesystemCursor'
+        - $ref: '#/components/parameters/FilesystemLimit'
+      responses:
+        '200':
+          description: One page of the folder.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/FilesystemListing'
+        '400':
+          $ref: '#/components/responses/BadRequest'
+        '401':
+          $ref: '#/components/responses/Unauthorized'
+        '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: '`task_package_not_retained` — the version keeps no package.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '429':
+          $ref: '#/components/responses/TooManyRequests'
+        '500':
+          $ref: '#/components/responses/InternalError'
+
+  /api/datasets/{name}/versions/{version}/tasks/{task_name}/filesystem/files/{path}:
+    get:
+      tags: [datasets]
+      operationId: readTaskPackageFile
+      summary: Read one file of the task package, raw bytes
+      description: |
+        The run file read (`readTrialFilesystemFile`) over the task
+        directory: raw bytes, a single `Range` honoured (206), the 413 above
+        the whole-read ceiling, 404 `not_found` for a path the package does
+        not hold, `X-Source: package`. A version that keeps no package is
+        409 `task_package_not_retained`.
+      parameters:
+        - $ref: '#/components/parameters/DatasetName'
+        - name: version
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: task_name
+          in: path
+          required: true
+          schema:
+            type: string
+        - name: path
           in: path
           required: true
+          description: The path inside the task directory, e.g. `tests/test.sh`.
+          schema:
+            type: string
+        - name: Range
+          in: header
+          description: Optional single byte range (`bytes=a-b` / `bytes=a-` / `bytes=-n`).
           schema:
             type: string
       responses:
         '200':
-          description: The task's build outcome.
+          description: The whole file.
           content:
-            application/json:
+            application/octet-stream:
               schema:
-                $ref: '#/components/schemas/TaskBuild'
+                type: string
+                format: binary
+        '206':
+          description: The requested byte range.
+          content:
+            application/octet-stream:
+              schema:
+                type: string
+                format: binary
+        '400':
+          $ref: '#/components/responses/BadRequest'
         '401':
           $ref: '#/components/responses/Unauthorized'
         '404':
+          $ref: '#/components/responses/NotFound'
+        '409':
+          description: '`task_package_not_retained` — the version keeps no package.'
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '413':
           description: >
-            `dataset_not_found`, `dataset_version_not_found`, or
-            `task_not_found` (no build outcome recorded under that name in
-            this version).
+            An unranged read above the whole-read ceiling (`invalid_input`,
+            param `Range`; details `size_bytes` / `max_unranged_bytes`).
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Error'
+        '416':
+          description: >
+            Range selects nothing inside the file (`invalid_input`;
+            `Content-Range` carries `bytes */<size>`).
           content:
             application/json:
               schema:
@@ -5053,6 +7283,11 @@ paths:
         parameter: a session has one owner and no organization, so `my` is
         the only visibility there is. The dashboard's own `admin=true` view
         is a session-cookie door — an API key that sends it is refused 403.
+        Each item (the same document `getSession` serves) carries the
+        session's identity — `agent`, `model`, `provider`, `sandboxId` — and
+        `reasoningEffort`, the effort the session was started with as the
+        SDK resolved it; null for a harness without one and for sessions
+        ingested before the field.
       parameters:
         - name: paginated
           in: query
@@ -5178,7 +7413,13 @@ paths:
       summary: Ingest session observability events
       description: >
         The SDK's observability push: session lifecycle and transcript events,
-        batched. Returns `{ success: true }` on acceptance.
+        batched. Returns `{ success: true }` on acceptance. The body carries
+        the session's identity (`tag`, `provider`, `agent`, `model`,
+        `sandboxId`, `timestamp`) beside the batch, and may carry
+        `reasoningEffort` — the effort the session was started with, as the
+        SDK resolved it: 1–32 characters of letters, digits, `_` or `-`,
+        else 400 `invalid_input` naming the field. The first ingest of a
+        session records it; a later ingest never overwrites a recorded value.
       requestBody:
         required: true
         content:
@@ -6098,6 +8339,45 @@ components:
         dataset route.
       schema:
         type: string
+    TaskCheckId:
+      name: taskCheckId
+      in: path
+      required: true
+      description: One task check's id (`results[].id` on the check); its file system is its own, under the check that owns it.
+      schema:
+        type: string
+        format: uuid
+    FilesystemSource:
+      name: source
+      in: query
+      description: >
+        Force the source: `live` (the running box) or `capture` (the kept
+        tree). Omitted, whichever the run has. A source that is not there
+        is 409 `filesystem_state`.
+      schema:
+        type: string
+        enum: [live, capture]
+    FilesystemPath:
+      name: path
+      in: query
+      description: An absolute box path (default `/`).
+      schema:
+        type: string
+        default: /
+    FilesystemCursor:
+      name: cursor
+      in: query
+      description: Resume after this cursor (the previous page's `next_cursor`).
+      schema:
+        type: string
+    FilesystemLimit:
+      name: limit
+      in: query
+      description: Page size; the route's default, max 1000.
+      schema:
+        type: integer
+        minimum: 1
+        maximum: 1000
     AgentName:
       name: name
       in: path
@@ -6539,6 +8819,13 @@ components:
         - org_member_not_found
         - invite_not_found
         - invite_invalid
+        # The file system + sandbox logs family (each code's meaning: its routes' responses).
+        - not_found
+        - not_captured
+        - filesystem_state
+        - feature_unsupported
+        - provider_unreachable
+        - task_package_not_retained
         # Fallback
         - internal_error
 
@@ -7428,6 +9715,15 @@ components:
           $ref: '#/components/schemas/RetryConfigInput'
         analyze:
           $ref: '#/components/schemas/AnalyzeConfigInput'
+        system_log:
+          type: boolean
+          default: false
+          description: >
+            Record the box's own SYSTEM log stream (the system journal or
+            log files) beside the agent, verifier, setup and metrics
+            streams every run keeps — read back at
+            `GET /api/trials/{trialId}/logs?stream=system`. Off by default:
+            it is one extra read-only reader inside a box under evaluation.
         timeout_multiplier:
           type: number
           exclusiveMinimum: 0
@@ -8441,6 +10737,7 @@ components:
         - agent_setup_timeout_multiplier
         - environment_build_timeout_multiplier
         - sandbox_provider
+        - system_log
         - counts
         - build_exclusions
         - n_total_trials
@@ -8504,6 +10801,13 @@ components:
             IT ran under). Derived jobs (resume, retry) inherit it verbatim
             — a re-run gets analyzed exactly like the trials it reproduces.
             Always null on a regrade job.
+        system_log:
+          type: boolean
+          description: >
+            Whether the run records the box's own SYSTEM log stream
+            (`JobCreate.system_log`), read back at `GET …/logs?stream=system`.
+            Derived jobs inherit it; always false on a regrade job and on
+            every job created before the switch existed.
         timeout_multiplier:
           type: number
           description: >
@@ -10206,6 +12510,14 @@ components:
         `--ek` (local-runner knobs with no hosted meaning), `-q` (a client
         rendering option, not a wire field).
       properties:
+        name:
+          type: string
+          minLength: 1
+          maxLength: 120
+          description: |
+            The caller's name for the check — Harbor's `--job-name` on
+            `harbor check` (cli/analyze.py:138). Omitted, the accept
+            timestamp in Harbor's own shape, `YYYY-MM-DD__HH-MM-SS` (UTC).
         model_name:
           type: string
           default: openrouter/deepseek/deepseek-v4.1-flash
@@ -10391,6 +12703,7 @@ components:
         of the measured task costs, null when none was measured.
       required:
         - id
+        - name
         - status
         - source
         - model_name
@@ -10410,6 +12723,9 @@ components:
         id:
           type: string
           format: uuid
+        name:
+          type: string
+          description: The caller's name, or the accept timestamp in Harbor's `YYYY-MM-DD__HH-MM-SS` shape.
         status:
           type: string
           enum: [queued, running, completed]
@@ -10459,6 +12775,33 @@ components:
           format: date-time
           description: When the last task settled; null until every task has.
 
+    CheckDefaults:
+      type: object
+      description: >
+        The policy an empty `CheckConfigInput` resolves to (GET
+        /api/checks/defaults) — each key the same value `Check` echoes for
+        a check created with no config, except `prompt`, which `Check`
+        serves as null (the built-in body) and this serves as that body's
+        template text.
+      required: [model_name, rubric, prompt, reasoning_effort, sandbox_provider]
+      properties:
+        model_name:
+          type: string
+        rubric:
+          $ref: '#/components/schemas/Rubric'
+        prompt:
+          type: string
+          description: >
+            The built-in check prompt template, unrendered — pass it as
+            `CheckConfigInput.prompt` to run the default body explicitly,
+            or edit it from here.
+        reasoning_effort:
+          type: string
+          description: The effort the default model runs at when the config names none.
+        sandbox_provider:
+          allOf:
+            - $ref: '#/components/schemas/SandboxProvider'
+
     CheckPage:
       type: object
       description: Cursor page of task quality checks (envelope keys frozen verbatim).
@@ -10781,6 +13124,324 @@ components:
         hasMore:
           type: boolean
 
+    # The file system + sandbox logs family: one set of shapes under every run owner and the task package.
+
+    FilesystemState:
+      type: string
+      description: >
+        Which source the file system routes answer from: `live` (the box
+        runs), `captured` (the kept tree), `capturing` (the capture is being
+        written), `none` (nothing to read).
+      enum: [live, captured, none, capturing]
+
+    FilesystemBox:
+      type: object
+      description: The running box a live file system reads.
+      required: [provider, id, role, since]
+      properties:
+        provider:
+          $ref: '#/components/schemas/SandboxProvider'
+        id:
+          type: string
+        role:
+          type: string
+          enum: [agent, verifier, analyzer, checker]
+        since:
+          type: string
+          format: date-time
+
+    FilesystemCapture:
+      type: object
+      description: The kept tree's record.
+      required: [id, at, phase, entries, changed_files, changed_bytes, status, left_out, failure_reason]
+      properties:
+        id:
+          type: string
+        at:
+          type: [string, 'null']
+          format: date-time
+          description: When the capture settled; null on one abandoned mid-way.
+        phase:
+          type: string
+          enum: [after_verifier, after_seal, after_run]
+          description: >
+            The moment it was taken at: after a shared verifier ran in the box,
+            after the seal (a separate verifier runs elsewhere), or after a run
+            that failed.
+        entries:
+          type: integer
+        changed_files:
+          type: integer
+        changed_bytes:
+          type: integer
+        status:
+          type: string
+          enum: [ready, incomplete, failed]
+        left_out:
+          type: array
+          items:
+            type: string
+          description: Every path the run touched whose bytes are not stored (`incomplete`), in the capture's order.
+        failure_reason:
+          type: [string, 'null']
+          description: Why a `failed` capture stored nothing; null otherwise.
+
+    FilesystemStatus:
+      type: object
+      required: [state, box, watcher, root, work_dir, capture]
+      properties:
+        state:
+          $ref: '#/components/schemas/FilesystemState'
+        box:
+          oneOf:
+            - $ref: '#/components/schemas/FilesystemBox'
+            - type: 'null'
+        watcher:
+          type: [string, 'null']
+          enum: [native, poll, null]
+          description: How live change events arrive; null when not live.
+        root:
+          type: string
+          description: Always `/`.
+        work_dir:
+          type: string
+          description: Where the run works (Harbor's `/app`).
+        capture:
+          oneOf:
+            - $ref: '#/components/schemas/FilesystemCapture'
+            - type: 'null'
+
+    TaskPackageFilesystemStatus:
+      type: object
+      description: The task package owner's status — the run shape with `state` always `none`, plus the package facts.
+      required: [state, box, watcher, root, work_dir, capture, source, package_retained]
+      properties:
+        state:
+          type: string
+          enum: [none]
+        box:
+          type: 'null'
+        watcher:
+          type: 'null'
+        root:
+          type: string
+        work_dir:
+          type: string
+        capture:
+          type: 'null'
+        source:
+          type: string
+          enum: [package]
+        package_retained:
+          type: boolean
+
+    FilesystemEntry:
+      type: object
+      description: One entry of a folder listing.
+      required: [name, type, size, mtime, mode, owner, changed, phase, captured]
+      properties:
+        name:
+          type: string
+        type:
+          type: string
+          enum: [dir, file, symlink, other]
+        size:
+          type: integer
+        mtime:
+          type: string
+          format: date-time
+        mode:
+          type: string
+          description: Octal, four digits, e.g. `0644`; the same words from both sources.
+        owner:
+          type: string
+          description: The owning user as the box names it, e.g. `root`; the same words from both sources.
+        changed:
+          type: [string, 'null']
+          enum: [created, modified, null]
+          description: What the run did to it since the box started; null when not known for the source.
+        phase:
+          type: [string, 'null']
+          enum: [setup, agent, verifier, null]
+          description: Which part of the run changed it — the platform's own setup, the agent, or the verifier.
+        captured:
+          type: [boolean, 'null']
+          description: >
+            Captured source: false = the run never touched it, only the
+            image holds it (lists, does not open). Live: null. Package: true.
+        left_out:
+          type: string
+          description: Captured source, a file the run touched whose bytes are not stored — why, in the capture's own words.
+        target:
+          type: string
+          description: A symlink's target.
+
+    FilesystemListing:
+      type: object
+      required: [path, source, entries, next_cursor, ms]
+      properties:
+        path:
+          type: string
+        source:
+          type: string
+          enum: [live, capture, package]
+        entries:
+          type: array
+          items:
+            $ref: '#/components/schemas/FilesystemEntry'
+        next_cursor:
+          type: [string, 'null']
+        ms:
+          type: integer
+          description: Server time spent, milliseconds.
+
+    FilesystemSearchHit:
+      type: object
+      required: [path, line, snippet]
+      properties:
+        path:
+          type: string
+        line:
+          type: integer
+        snippet:
+          type: string
+
+    FilesystemSearchResult:
+      type: object
+      required: [hits, truncated, scope, source, ms]
+      properties:
+        hits:
+          type: array
+          items:
+            $ref: '#/components/schemas/FilesystemSearchHit'
+        truncated:
+          type: boolean
+          description: More hits exist, or the search budget ran out.
+        scope:
+          type: string
+          enum: [path, box]
+        source:
+          type: string
+          enum: [live, capture]
+        image_files_excluded:
+          type: boolean
+          description: Captured source only — files the run never touched were not searchable.
+        ms:
+          type: integer
+
+    FilesystemChange:
+      type: object
+      required: [path, type, changed, phase, size, mtime]
+      properties:
+        path:
+          type: string
+        type:
+          type: string
+          enum: [dir, file, symlink, other]
+        changed:
+          type: string
+          enum: [created, modified, removed]
+        phase:
+          type: string
+          enum: [setup, agent, verifier]
+        size:
+          type: integer
+        mtime:
+          type: string
+          format: date-time
+        left_out:
+          type: string
+          description: Captured source, a file whose bytes are not stored — why, in the capture's own words.
+
+    FilesystemChanges:
+      type: object
+      required: [source, total, changed_bytes, items, next_cursor]
+      properties:
+        source:
+          type: string
+          enum: [live, capture]
+        total:
+          type: integer
+        changed_bytes:
+          type: integer
+        items:
+          type: array
+          items:
+            $ref: '#/components/schemas/FilesystemChange'
+        next_cursor:
+          type: [string, 'null']
+
+    FilesystemWatchRequest:
+      type: object
+      required: [paths]
+      properties:
+        paths:
+          type: array
+          maxItems: 8
+          items:
+            type: string
+          description: The folders the viewer has open, absolute box paths; replaces the set.
+
+    FilesystemWatchResult:
+      type: object
+      required: [watcher, paths]
+      properties:
+        watcher:
+          type: string
+          enum: [native, poll]
+        paths:
+          type: array
+          items:
+            type: string
+
+    SandboxLogStream:
+      type: string
+      description: The named sandbox streams a run records.
+      enum: [agent, verifier, setup, system, metrics]
+
+    SandboxLogLine:
+      type: object
+      required: [seq, t, fd, line]
+      properties:
+        seq:
+          type: integer
+        t:
+          type: [string, 'null']
+          format: date-time
+          description: When the line was recorded; null when the record holds no time for it.
+        fd:
+          type: string
+          enum: [out, err]
+        line:
+          type: string
+
+    SandboxLogLines:
+      type: object
+      description: One page of a stream.
+      required: [stream, lines, next_cursor]
+      properties:
+        stream:
+          $ref: '#/components/schemas/SandboxLogStream'
+        lines:
+          type: array
+          items:
+            $ref: '#/components/schemas/SandboxLogLine'
+        next_cursor:
+          type: [string, 'null']
+        reason:
+          type: string
+          description: Why the page is empty when the platform holds nothing for this stream (never an error).
+
+    SandboxProcs:
+      type: object
+      required: [text, ms]
+      properties:
+        text:
+          type: string
+          description: The process listing as text.
+        ms:
+          type: integer
+
     # -------------------------------------------------------------------------
     # Job archive (the downloadJob tar) — the Evolve extension keys inside the
     # otherwise Harbor-vocabulary record files. Not HTTP bodies: these schemas