feat(store): harden pilot workspace operator flow

Author: eblackrps

CHANGELOG.md

@@ -6,6 +6,22 @@ This changelog tracks published releases and the major implementation milestones
 
 ## [Unreleased]
 
+## [1.7.0] - 2026-04-11
+
+### Workspace Reliability And Operator Hardening
+- added stricter validation for pilot workspace create, update, job, and report-export requests so invalid operator input fails early with field-level API errors
+- added read-only workspace access for viewer principals while keeping workspace mutation and job execution operator-scoped
+- added workspace deletion, restart recovery for queued or running workspace jobs, configurable workspace job timeouts, and richer exported report handoff detail
+
+### Dashboard And Operator Experience
+- switched runtime dashboard auth to session-scoped storage by default with an explicit remember option for trusted browsers
+- added workspace creation toggles, persisted job history, retry actions, and clearer correlation-aware job states in the workspace-first flow
+
+### Release Engineering, Docs, And Contract
+- hardened the Windows release-gate helpers so race, coverage, and CLI smoke validation remain reproducible on Application Control-constrained operator workstations
+- documented `VIADUCT_ALLOWED_ORIGINS` and `VIADUCT_WORKSPACE_JOB_TIMEOUT`
+- updated the pilot workspace guide, quickstarts, installation guides, and OpenAPI contract to match the hardened workspace and auth behavior
+
 ## [1.6.0] - 2026-04-11
 
 ### Workspace-First Operator Flow

INSTALL.md

@@ -63,4 +63,6 @@ The cleanest evaluation path is still the local lab in [examples/lab](examples/l
 For packaged or persistent evaluation environments:
 - use PostgreSQL instead of the in-memory store
 - prefer service-account keys for normal operator access
+- set `VIADUCT_ALLOWED_ORIGINS` if the dashboard is served from anything other than the default local Vite origins
+- tune `VIADUCT_WORKSPACE_JOB_TIMEOUT` if discovery or planning jobs need a different server-side timeout budget
 - keep the Vite dev server out of any shared or internet-facing environment

QUICKSTART.md

@@ -45,6 +45,8 @@ $env:VIADUCT_ADMIN_KEY = "lab-admin"
 .\bin\viaduct.exe serve-api --port 8080
 ```
 
+The API accepts browser requests from the default local dashboard origins (`http://localhost:5173`, `http://127.0.0.1:5173`, `http://localhost:4173`, `http://127.0.0.1:4173`). If you serve the dashboard from a different origin, set `VIADUCT_ALLOWED_ORIGINS` before starting the API.
+
 ## 4. Seed The Lab Tenant And Service Account
 
 ```bash
@@ -81,6 +83,8 @@ Authenticate with:
 - preferred: `lab-operator-key`
 - bootstrap only: `lab-tenant-key`
 
+The dashboard stores the runtime key in session storage by default. Use the remember option only when you intentionally want the browser to keep a local copy across restarts.
+
 ## 6. Run The Workspace-First Flow
 
 In the dashboard:

README.md

@@ -80,6 +80,10 @@ curl -X POST \
 
 Then start the dashboard in `web/`, sign in with `lab-operator-key`, and run the workspace-first flow.
 
+The runtime bootstrap stores keys in the browser session by default. Use the optional remember toggle only on a trusted workstation.
+
+If you serve the dashboard from a non-default origin, configure `VIADUCT_ALLOWED_ORIGINS` on the API so the browser can reach tenant-protected routes.
+
 Use these entrypoints next:
 - Quickstart: [QUICKSTART.md](QUICKSTART.md)
 - Detailed quickstart: [docs/getting-started/quickstart.md](docs/getting-started/quickstart.md)

docs/getting-started/installation.md

@@ -31,7 +31,7 @@ npm run build
 Generate a self-contained local bundle:
 
 ```bash
-make package-release
+make package-release-matrix
 ```
 
 This creates:
@@ -92,3 +92,8 @@ viaduct --help
 ```
 
 If you installed only the CLI and not the dashboard assets, the API and migration/lifecycle backends still work; only the packaged static web assets are absent.
+
+For browser access in packaged environments:
+- set `VIADUCT_ALLOWED_ORIGINS` if the dashboard is served from a non-default origin
+- prefer service-account keys for normal operator access
+- use `VIADUCT_WORKSPACE_JOB_TIMEOUT` if workspace jobs need a different server-side timeout budget

docs/getting-started/quickstart.md

@@ -39,6 +39,8 @@ export VIADUCT_ADMIN_KEY=lab-admin
 ./bin/viaduct serve-api --port 8080
 ```
 
+The API accepts browser requests from the default local dashboard origins (`http://localhost:5173`, `http://127.0.0.1:5173`, `http://localhost:4173`, `http://127.0.0.1:4173`). For any other dashboard origin, set `VIADUCT_ALLOWED_ORIGINS` before starting the API.
+
 In another terminal, create the lab tenant and operator service account:
 
 ```bash
@@ -69,6 +71,8 @@ Authenticate through the runtime bootstrap screen:
 - preferred service-account key: `lab-operator-key`
 - bootstrap-only tenant key: `lab-tenant-key`
 
+The runtime key is kept in session storage by default. Use the remember option only when you intentionally want the browser to keep a local copy across restarts.
+
 For packaged or persistent environments, prefer `VITE_VIADUCT_SERVICE_ACCOUNT_KEY` over `VITE_VIADUCT_API_KEY` so operator activity is attributable to a named service account instead of the tenant-wide admin credential.
 
 ## 5. Run The Workspace-First Operator Flow

docs/operations/pilot-workspace-flow.md

@@ -84,12 +84,16 @@ Authenticate in one of two ways:
 - Preferred: choose `Service account` and paste `lab-operator-key`
 - Bootstrap only: choose `Tenant key` and paste `lab-tenant-key`
 
+The dashboard stores the runtime key in session storage by default. Use the optional remember toggle only on a trusted browser that should keep the key across restarts.
+
 You can still pre-seed development credentials with:
 - `VITE_VIADUCT_SERVICE_ACCOUNT_KEY`
 - `VITE_VIADUCT_API_KEY`
 
 The runtime bootstrap flow is the canonical operator path because it works for packaged environments and does not require a rebuild to rotate credentials.
 
+The API accepts browser requests from the default local dashboard origins. If you serve the dashboard from another host or port, set `VIADUCT_ALLOWED_ORIGINS` before starting the API.
+
 ## 5. Run The Workspace-First Operator Flow
 
 Inside the dashboard:
@@ -103,6 +107,8 @@ Inside the dashboard:
 
 The workspace keeps the discovery baseline, readiness result, saved plan, notes, approvals, and report history attached to the same object.
 
+Read-only operators can inspect workspace state and export reports with viewer access, but only operator-level principals can mutate workspace state or start jobs.
+
 ## API Equivalents
 
 If you want to exercise the same flow through the REST API, the seeded request body below matches the default dashboard intake:
@@ -158,6 +164,10 @@ The workspace flow is correlation-aware:
 
 If a step fails, capture the request ID and workspace/job identifier together. That is the intended operator handoff bundle for troubleshooting.
 
+Queued or running workspace jobs are recovered when the API starts again, and each job is subject to the server-side timeout configured by `VIADUCT_WORKSPACE_JOB_TIMEOUT`.
+
+If you want to discard a completed evaluation workspace, delete it through the dashboard or `DELETE /api/v1/workspaces/{workspaceID}`. That removes the workspace record and its job history, but it does not purge persisted snapshots or migration records outside the workspace document.
+
 ## Smoke Coverage
 
 The deterministic end-to-end lab smoke now lives in:

docs/reference/configuration.md

@@ -55,14 +55,16 @@ Fields:
 - `VIADUCT_PASSWORD`: overrides config file password for CLI connector auth
 - `VIADUCT_ADMIN_KEY`: admin API key used by the REST server for tenant administration
 - `VIADUCT_PLUGIN_ADDR`: plugin listener address used by community connector plugins
+- `VIADUCT_ALLOWED_ORIGINS`: comma-separated browser origins allowed to call the API from another origin; defaults to the local Vite origins on ports `5173` and `4173`
+- `VIADUCT_WORKSPACE_JOB_TIMEOUT`: per-job server-side timeout for pilot workspace discovery, graph, simulation, and plan generation; defaults to `2m`
 
 ## Dashboard Environment Variables
 - `VITE_VIADUCT_API_KEY`: tenant API key injected into dashboard requests
 - `VITE_VIADUCT_SERVICE_ACCOUNT_KEY`: scoped service-account key injected into dashboard requests; when set, the dashboard prefers this header over `VITE_VIADUCT_API_KEY`
 
 The dashboard reads this through Vite. See [`../../web/.env.example`](../../web/.env.example).
 
-The dashboard now also supports runtime authentication bootstrap. When neither variable is set, the app starts on a bootstrap screen and accepts either a service-account key or tenant key at runtime. The selected credential is stored locally by the browser and reused for subsequent requests until the operator signs out or rotates the key.
+The dashboard now also supports runtime authentication bootstrap. When neither variable is set, the app starts on a bootstrap screen and accepts either a service-account key or tenant key at runtime. The selected credential is stored in browser session storage by default and is cleared when the browser session ends. Operators can explicitly choose to remember the key in local storage on trusted workstations.
 
 For early-product and pilot use, prefer `VITE_VIADUCT_SERVICE_ACCOUNT_KEY` for normal dashboard access. Reserve `VITE_VIADUCT_API_KEY` for tenant bootstrap, short-lived admin work, or break-glass access.
 

docs/reference/openapi.yaml

@@ -476,6 +476,28 @@ paths:
           $ref: "#/components/responses/ErrorResponse"
         "500":
           $ref: "#/components/responses/ErrorResponse"
+    delete:
+      summary: Delete a pilot workspace
+      security:
+        - TenantAPIKey: []
+        - ServiceAccountKey: []
+      parameters:
+        - in: path
+          name: workspaceID
+          required: true
+          schema:
+            type: string
+      responses:
+        "204":
+          description: Pilot workspace deleted
+        "401":
+          $ref: "#/components/responses/ErrorResponse"
+        "403":
+          $ref: "#/components/responses/ErrorResponse"
+        "404":
+          $ref: "#/components/responses/ErrorResponse"
+        "500":
+          $ref: "#/components/responses/ErrorResponse"
     patch:
       summary: Update pilot workspace state
       security:

docs/reference/troubleshooting.md

@@ -48,6 +48,36 @@ Fix:
 - prefer `VITE_VIADUCT_SERVICE_ACCOUNT_KEY` for normal dashboard use
 - confirm API health at `/api/v1/health`
 
+## Browser Reports `origin not allowed`
+
+Cause:
+- the dashboard is running from an origin that the API CORS allowlist does not trust
+
+Fix:
+- set `VIADUCT_ALLOWED_ORIGINS` to a comma-separated list of trusted dashboard origins
+- restart `viaduct serve-api`
+- keep the value narrow instead of using a wildcard
+
+## Workspace Job Fails With `context deadline exceeded`
+
+Cause:
+- the server-side workspace job timeout elapsed before discovery, graph generation, simulation, or planning completed
+
+Fix:
+- increase `VIADUCT_WORKSPACE_JOB_TIMEOUT`
+- retry the job from the workspace job history after adjusting the timeout
+- use PostgreSQL for persistent evaluation environments so retry and recovery state survive restarts
+
+## Dashboard Sign-In Disappears After Closing The Browser
+
+Cause:
+- the runtime bootstrap stores keys in session storage by default
+
+Fix:
+- sign in again
+- use the bootstrap screen's remember option if you intentionally want the browser to keep a local copy of the key
+- prefer service-account keys over tenant keys for saved browser credentials
+
 ## KVM Fixture Discovery Returns No VMs
 
 Cause: