Expose retained runs through service API

docs/SERVICE-JOB-DURABILITY.md

@@ -13,16 +13,19 @@ Durable state lives in run directories:
 
 - `run.json`
 - `plan.json`
+- `sources.lock.json`
 - `retention-summary.json`
 - `normalized/evidence.json`
 - `normalized/findings.json`
 - `normalized/mappings.json`
 - `reports/assessment-package.json`
 - `reports/report.md`
+- `reports/submission-package.json`
 - `artifacts/`
 
 The durable recovery index is the set of `retention-summary.json` files under a
-runs directory.
+runs directory. No separate durable service index is required for the baseline;
+the service reconstructs retained-run views by scanning those summaries.
 
 ## Why In-Memory Jobs Stay The Baseline
 
@@ -47,9 +50,14 @@ After a service restart:
 - old `job_id` values are invalid,
 - `GET /runs/{job_id}` cannot recover pre-restart job metadata,
 - `GET /runs/{job_id}/reports` only works for jobs known to the current process,
-- run artifacts from earlier service processes remain available on disk.
+- run artifacts from earlier service processes remain available on disk,
+- `GET /retained-runs`, `GET /retained-runs/latest`,
+  `GET /retained-runs/{run_id}/reports`, and
+  `GET /retained-runs/{run_id}/artifact-manifest` can expose completed retained
+  runs after restart.
 
-Operators should recover previous results with the CLI run-history commands:
+Operators can recover previous results with either the CLI run-history commands
+or the retained-run service endpoints:
 
 ```sh
 PYTHONPATH=src python3 -m guide_board runs list --runs-dir runs
@@ -57,6 +65,12 @@ PYTHONPATH=src python3 -m guide_board runs latest --runs-dir runs
 PYTHONPATH=src python3 -m guide_board runs report --runs-dir runs --run-id RUN_ID
 ```
 
+```sh
+curl -sf "http://127.0.0.1:8080/retained-runs?runs_dir=runs" | python3 -m json.tool
+curl -sf "http://127.0.0.1:8080/retained-runs/RUN_ID/reports?runs_dir=runs" | python3 -m json.tool
+curl -sf "http://127.0.0.1:8080/retained-runs/RUN_ID/artifact-manifest?runs_dir=runs" | python3 -m json.tool
+```
+
 ## Recovery Flow
 
 Use this flow when the service process restarted or a browser/UI lost its job
@@ -64,8 +78,9 @@ state:
 
 1. Identify the output directory passed to `POST /runs`.
 2. Confirm whether `retention-summary.json` exists.
-3. If it exists, use `guide-board runs report --runs-dir <parent>` to retrieve
-   report paths.
+3. If it exists, use `guide-board runs report --runs-dir <parent>` or
+   `GET /retained-runs/{run_id}/reports?runs_dir=<parent>` to retrieve report
+   paths.
 4. If only partial files exist, inspect `run.json`, `plan.json`, and artifacts
    before rerunning.
 5. Rerun into a fresh output directory when the prior status is unclear.
@@ -73,8 +88,8 @@ state:
 ## Future Durable Index Option
 
 A future durable service index may be added if UI or automation workflows need
-cross-restart job lookup. If added, it should remain reconstructable from run
-directories and should not become the authority for assessment results.
+cross-restart transport job lookup. If added, it should remain reconstructable
+from run directories and should not become the authority for assessment results.
 
 The minimum acceptable durable index would contain: