feat: Enhance validation and normalization of run artifacts, including event logs and background job records

Author: lhy0718

docs/architecture.md

@@ -28,20 +28,28 @@ Until those conditions are met, treat the 9-node workflow as fixed.
 
 - TUI (`autolabos`) and local web ops UI (`autolabos web`) share the same interaction/runtime layer.
 - Node execution and transitions are controlled by `StateGraphRuntime`.
+- Runtime events are persisted per run in `.autolabos/runs/<run-id>/events.jsonl`; high-churn telemetry should go there rather than into `runs.json`.
+- Deferred `collect_papers` recovery state is persisted in `.autolabos/runs/<run-id>/collect_background_job.json` whenever background enrichment is active, so restart recovery stays inspectable.
 - Approval mode and transition recommendation behavior are part of runtime contracts.
+- `/approve` must respect stored non-advance pending transitions (for example `analyze_results -> backtrack_to_design`) instead of advancing by graph order. Explicit manual `/agent run <next-node>` handoffs may resume `pause_for_human` transitions without weakening default approval behavior.
 
 Harness and runtime work must preserve both TUI and web behaviors unless a change is explicitly requested.
 
 ## 3) Artifact model
 
 - Run-scoped source of truth: `.autolabos/runs/<run-id>/...`
+- Lightweight run index/projection: `.autolabos/runs/runs.json` (status, node pointer, aggregate `usage`)
 - Public mirrored outputs: `outputs/` (single latest-run public bundle)
 - Checkpoints and run context are persisted under each run directory.
+- Design/execution experiment contracts live in `experiment_portfolio.json` and `run_manifest.json`.
+- Transition/gate decisions remain inspectable through artifacts such as `transition_recommendation.json`, `analysis/evidence_scale_assessment.json`, `review/*`, and `paper/write_paper_eligibility.json`.
 
 Quality checks should be deterministic and file-based whenever possible.
 
 Public-facing outputs must remain traceable to underlying run artifacts.
 
+Because events, checkpoints, background-job recovery, and execution artifacts already live in per-run files, `runs.json` should stay a summary index rather than a sink for append-only logs. If index write contention becomes material, split the summary index or move it to sqlite instead of pushing more high-volume data into `runs.json`.
+
 ## 4) Node-internal loops are bounded
 
 Internal control loops inside nodes are allowed and expected, including loops in analysis, design, implementation, execution, result interpretation, and writing.

docs/reproducibility.md

@@ -4,19 +4,24 @@ Reproducibility claims must be backed by concrete artifacts.
 
 ## 1) Minimum artifact set (when applicable)
 
+- Runtime event trace (`events.jsonl`)
+- Deferred background recovery record when used (`collect_background_job.json`)
 - Planned portfolio / trial-group structure (`experiment_portfolio.json`)
 - Run manifest (`run_manifest.json`)
 - Raw or summarized metrics (`metrics.json`, supplemental metrics)
 - Objective evaluation (`objective_evaluation.json`)
 - Result synthesis (`result_analysis.json`, optional synthesis artifact)
+- Transition decision (`transition_recommendation.json`)
 - Paper trace outputs (`paper/main.tex`, `paper/references.bib`, `paper/evidence_links.json`)
 
 ## 2) Run-state traceability
 
 For each run, preserve:
 
 - run id
-- workflow node progression (`runs.json`)
+- workflow node progression (`runs.json`) including current node/status and aggregate usage when available
+- append-only runtime events (`events.jsonl`)
+- key gate/recovery artifacts (`transition_recommendation.json`, `collect_background_job.json` when present)
 - key generated artifacts in `.autolabos/runs/<run_id>/...`
 
 ## 3) Reproducibility claim language
@@ -29,12 +34,12 @@ For each run, preserve:
 Before marking work complete:
 
 1. Re-run the relevant flow or tests.
-2. Confirm expected artifacts are present and parseable.
+2. Confirm expected artifacts are present, parseable, and consistent across `runs.json`, `events.jsonl`, and run-scoped artifacts.
 3. Record limitations and unresolved uncertainty.
 
 ## 5) Validation surfaces
 
 - Runtime diagnostics: `/doctor` in TUI and web Doctor tab (environment + workspace harness checks).
-- CI/internal gate: `npm run validate:harness` (issue log format + workspace/test run artifact structure).
+- CI/internal gate: `npm run validate:harness` (issue log format + workspace/test run artifact structure, including event logs and portfolio/manifest contracts).
 
-No separate end-user command is required beyond `/doctor`.
+No separate end-user command is required beyond `/doctor`, but maintainers should still run `npm run validate:harness` before declaring artifact-level reproducibility complete.

src/core/runs/migrateRuns.ts

@@ -6,6 +6,7 @@ import {
   RunsFile
 } from "../../types.js";
 import { createDefaultGraphState } from "../stateGraph/defaults.js";
+import { normalizeRunUsageSummary } from "./runUsage.js";
 
 type StageIdV1 =
   | "collect"
@@ -207,6 +208,7 @@ function normalizeRunsV3(file: RunsFile): RunsFile {
       version: 3,
       workflowVersion: 3,
       nodeThreads: run.nodeThreads ?? {},
+      usage: normalizeRunUsageSummary(run.usage),
       graph: {
         ...createDefaultGraphState(),
         ...run.graph,

src/core/validation/harnessValidationService.ts

@@ -257,6 +257,15 @@ export function defaultRemediationForIssueCode(code: string): string {
   if (code.includes("paper_result")) {
     return "Regenerate paper artifacts after run_experiments/analyze_results, or remove unsupported result claims from the manuscript.";
   }
+  if (code.includes("events_log")) {
+    return "Ensure every started run writes parseable JSONL events to .autolabos/runs/<run-id>/events.jsonl.";
+  }
+  if (code.includes("run_manifest") || code.includes("experiment_portfolio")) {
+    return "Regenerate design/run artifacts so experiment_portfolio.json and run_manifest.json are present and structurally consistent.";
+  }
+  if (code.includes("collect_background_job")) {
+    return "Rewrite or clear collect_background_job.json so deferred enrichment recovery metadata matches the current run.";
+  }
   if (code.includes("review_")) {
     return "Align review decision artifacts, run status, and paper output state before marking the run as completed.";
   }