fix(cli): show splash screen on bare invocation and setup (#425)

* refactor(cli): list workspaces natively instead of via the worker image

* feat(cli): preflight that Docker is installed and running

* feat(cli): stop scans by workspace or --all, terminating their Temporal workflows

* fix(worker): abort the running agent on cancellation so Temporal cancel takes effect

* refactor(cli): split destructive teardown out of stop into a reset command

* refactor(cli): centralise flag parsing and confirmation across commands

* fix(cli): pass provider credentials to docker by name to keep secrets out of argv

* feat(cli): add per-command help via <command> --help/-h and help <command>

* feat(cli): replace raw docker output with clack spinners for infra and scan teardown

* fix(cli): verify scan stop by re-querying container and workflow state instead of assuming success

* fix(cli): resolve running state before prompting on stop and report no-op stops honestly

* refactor(cli): show splash first and drive start with one spinner resolving to a clean line

* fix(cli): validate --url up front so a bad value fails cleanly instead of a late crash

* refactor(cli): centralize error reporting with fail() for expected errors and a crash handler that logs the stack and links the issue tracker

* feat(cli): add --json/--plain machine-readable output to workspaces and status

* refactor(cli): remove the workspaces command

* refactor(cli): remove the status command

* feat(cli): add 'progress <workspace>' — live scan progress from Temporal

* fix(cli): mark metric-less agents as skipped in progress, not done

* feat(cli): animate running agents in progress with a clack-style spinner

* feat(cli): rename progress->status, reveal agents as they run, show live per-agent elapsed

* fix(cli): mark passed-over phases as skipped live, not pending

* style(cli): rename status footer 'Wall-clock' to 'Time Taken', drop the parenthetical

* style(cli): drop '(sum of agents)' from status total cost line

* style(cli): green filled circle for completed, Shannon gold for running

* style(cli): use Shannon gold in place of green in status

* feat(cli): suggest closest command or flag on typo

* refactor(cli): single-source start help and drop ./repos bare-name shortcut

* feat(cli): name providers and fix in multi-provider credential error

* feat(cli): support --flag=value syntax and expand leading ~ in paths

* refactor(cli): centralize ANSI color codes in colors.ts

* feat(cli): add scans command listing completed scans with cost and duration

* fix(cli): keep stdout clean off-TTY for logs and start

* feat(cli): add repo link to top-level help

* feat(worker): record auth-validation metrics and register resume attempts early

* refactor(cli): share resume-aware workflow-id resolution and surface root-cause failures

* feat(cli): add status --json, auth phase, dashboard link, and stable live redraw

* refactor(cli): drop cost from status and scans output

* feat(worker): surface both PDF and markdown report at run root

* refactor(cli): normalize error/warning prefixing through fail and warn

* feat(cli): add version --json for machine-readable output

* refactor(cli): rename start --debug to --keep-container

* refactor(cli): point start's progress hint at status instead of the Temporal dashboard

* refactor(cli): centralize the mode-aware command prefix

* refactor(cli): trim start and logs output to durable facts off-TTY

* feat(cli): require typed confirmation for reset instead of --yes

reset permanently wipes all Temporal data and volumes — a severe,
irreversible action. Replace its default y/N confirm (bypassable with
--yes) with a typed-word confirmation that has no bypass, so the wipe
can only be triggered by a deliberate interactive answer.

* feat(cli): surface logs and status hints after start on a TTY

* feat(cli): exit 2 on usage errors, distinct from operational failures

* feat(cli): add start --follow to stream logs and exit on scan outcome

* refactor(cli): redesign splash with sunset-gradient wordmark and truecolor

* refactor(cli): remove the uninstall command

* docs: sync CLI docs with removed uninstall/workspaces, new scans and --follow

* docs: fix reset confirmation — typed confirm, not --yes/-y

* style(cli): restructure status footer with divider, aligned Logs/Temporal rows

* feat(cli): show splash in the status command

* fix(worker): validate auth-state shape, not entry count

* docs: correct reset confirmation and add markdown report to run-root docs

.env.example

@@ -3,16 +3,16 @@
 # Defaults to anthropic:claude-sonnet-4-6.
 
 # --- Anthropic ---------------------------------------------------------------
-ANTHROPIC_API_KEY=your-api-key-here
+SHANNON_AI_API_KEY=your-api-key-here
 SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 # CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 
 # --- OpenAI ------------------------------------------------------------------
-# OPENAI_API_KEY=your-api-key-here
-# SHANNON_AI_MODEL=openai:gpt-5.6-sol
+# SHANNON_AI_API_KEY=your-api-key-here
+# SHANNON_AI_MODEL=openai:gpt-5.5
 
 # --- xAI ---------------------------------------------------------------------
-# XAI_API_KEY=your-api-key-here
+# SHANNON_AI_API_KEY=your-api-key-here
 # SHANNON_AI_MODEL=xai:grok-4.5
 
 # --- AWS Bedrock -------------------------------------------------------------
@@ -24,20 +24,32 @@ SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 # --- Custom Base URL ---------------------------------------------------------
 # Route through a proxy or gateway (LiteLLM, an internal endpoint).
 # Pick the block matching the API dialect your gateway speaks, and uncomment all
-# three lines. The provider prefix picks the dialect and which key is sent; the
-# model id is whatever name your gateway serves it under.
+# three lines. The provider prefix picks the dialect; the model id is whatever
+# name your gateway serves it under.
 
 # Anthropic compatible - Anthropic Messages:
-# ANTHROPIC_API_KEY=your-gateway-key-here
+# SHANNON_AI_API_KEY=your-gateway-key-here
 # SHANNON_AI_BASE_URL=https://llm-gateway.example.com
 # SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 
 # OpenAI compatible - Chat Completions (default) or Responses:
-# OPENAI_API_KEY=your-gateway-key-here
+# SHANNON_AI_API_KEY=your-gateway-key-here
 # SHANNON_AI_BASE_URL=https://llm-gateway.example.com/v1
-# SHANNON_AI_MODEL=openai:gpt-5.6-sol
+# SHANNON_AI_MODEL=openai:gpt-5.5
 # SHANNON_AI_OPENAI_FORMAT=responses
 
-# --- Other -------------------------------------------------------------------
+# --- Other provider ----------------------------------------------------------
+# Any other provider the Pi harness supports. Name it in SHANNON_AI_MODEL and
+# supply the key via the generic SHANNON_AI_API_KEY. Pi validates the provider
+# and model at preflight.
+# SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3
+# SHANNON_AI_API_KEY=your-api-key-here
+
+# --- Misc --------------------------------------------------------------------
 # Forward /etc/hosts entries into the worker container.
 # SHANNON_FORWARD_HOSTS=false
+
+# See the guide below to use an OpenAI subscription
+# https://github.com/KeygraphHQ/shannon/blob/main/docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription
+# SHANNON_USE_PI_AUTH=1
+# SHANNON_AI_MODEL=openai-codex:gpt-5.5

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -117,8 +117,12 @@ body:
       options:
         - "Anthropic (API key)"
         - "Anthropic (OAuth token)"
-        - "Custom base URL (proxy/gateway)"
+        - "OpenAI"
+        - "xAI"
         - "AWS Bedrock"
+        - "Custom base URL - Anthropic Messages"
+        - "Custom base URL - OpenAI Chat Completions"
+        - "Custom base URL - OpenAI Responses"
     validations:
       required: true
 

CLAUDE.md

@@ -44,8 +44,8 @@ echo "ANTHROPIC_API_KEY=your-key" > .env
 ./shannon build
 
 # Run
-./shannon start -u <url> -r my-repo
-./shannon start -u <url> -r my-repo -c ./apps/worker/configs/my-config.yaml
+./shannon start -u <url> -r ./my-repo
+./shannon start -u <url> -r ./my-repo -c ./apps/worker/configs/my-config.yaml
 ./shannon start -u <url> -r /any/path/to/repo
 ```
 
@@ -56,25 +56,24 @@ echo "ANTHROPIC_API_KEY=your-key" > .env
 npx @keygraph/shannon setup
 
 # Workspaces & Resume
-./shannon start -u <url> -r my-repo -w my-audit    # New named workspace
-./shannon start -u <url> -r my-repo -w my-audit    # Resume (same command)
-./shannon workspaces                                 # List all workspaces
+./shannon start -u <url> -r ./my-repo -w my-audit    # New named workspace
+./shannon start -u <url> -r ./my-repo -w my-audit    # Resume (same command)
 
 # Monitor
 ./shannon logs <workspace>            # Show a scan's live log
-./shannon status                      # Show running scans
+./shannon status <workspace>          # Live phase/agent progress of one scan, read from Temporal (redraws, then exits)
 # Dashboard: http://localhost:8233
 
 # Stop
-./shannon stop                        # Preserves scan data
-./shannon stop --clean                # Full cleanup including volumes (confirms first; --yes/-y to skip)
+./shannon stop <workspace>            # Stop one scan (confirms first; --yes/-y to skip)
+./shannon stop --all                  # Stop all running scans (Temporal stays up; confirms first)
+./shannon reset                       # Stop everything and wipe all Temporal data + volumes (type 'confirm' to proceed; cannot be skipped)
 
 # Version
 ./shannon version                     # npx: package version; local: git SHA
 
 # Image management
 ./shannon build [--no-cache]          # Local mode: build worker image
-npx @keygraph/shannon uninstall             # npx mode: remove ~/.shannon/ (confirms first; --yes/-y to skip)
 
 # Build TypeScript (development)
 pnpm run build                       # Build all packages via Turborepo
@@ -85,7 +84,7 @@ pnpm biome:fix                       # Auto-fix lint, format, and import sorting
 
 **Monorepo tooling:** pnpm workspaces, Turborepo for task orchestration, Biome for linting/formatting. TypeScript compiler options shared via `tsconfig.base.json` at the root. All packages extend it, overriding only `rootDir` and `outDir`. Shared devDependencies (`typescript`, `@types/node`, `turbo`, `@biomejs/biome`) are hoisted to the root workspace.
 
-**Options:** `-c <file>` (YAML config), `-o <path>` (output directory), `-w <name>` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--debug` (preserve worker container after exit for log inspection), `--yes`/`-y` (skip the confirmation prompt on `stop --clean`/`uninstall`; required for non-interactive use)
+**Options:** `-c <file>` (YAML config), `-o <path>` (output directory), `-w <name>` (named workspace; auto-resumes if exists), `--pipeline-testing` (minimal prompts, 10s retries), `--keep-container` (preserve worker container after exit for log inspection), `--yes`/`-y` (skip the confirmation prompt on `stop`; required for non-interactive use; `reset` requires a typed `confirm` and cannot be skipped)
 
 ## Architecture
 
@@ -97,9 +96,11 @@ apps/worker/     — @shannon/worker (private, Temporal worker + pipeline logic)
 ```
 
 ### CLI Package (`apps/cli/`)
-Published as `@keygraph/shannon` on npm. Contains only Docker orchestration logic — no Temporal SDK, business logic, or prompts. Bundled with tsdown for single-file ESM output.
+Published as `@keygraph/shannon` on npm. Contains Docker orchestration logic plus a read-only `@temporalio/client` reader (for `status`); no worker/pipeline business logic or prompts. Bundled with tsdown for single-file ESM output (deps stay external).
 
-- `apps/cli/src/index.ts` — CLI dispatcher (`setup`, `start`, `stop`, `logs`, `workspaces`, `status`, `build`, `uninstall`, `version`)
+- `apps/cli/src/index.ts` — CLI dispatcher (`setup`, `start`, `stop`, `reset`, `logs`, `status`, `build`, `version`)
+- `apps/cli/src/temporal-client.ts` — `@temporalio/client` reader for `status`: connects to the frontend on `127.0.0.1:7233` (published by compose), `describeScan` (status + `pendingActivities` → running agents), `queryProgress` (live `getProgress` query → `PipelineState`), `getTerminalOutcome` (workflow `result()`). No worker of its own; scans are visible only within Temporal's ~24h retention (namespace default, unset in compose)
+- `apps/cli/src/scan/` — `status` rendering: `pipeline.ts` (static phase/agent plan + `run*Agent` activity-type→agent map + mirrored `PipelineState`/`AgentMetrics` types; keep in sync with the worker), `render.ts` (one renderer for both the live query state and the terminal result)
 - `apps/cli/src/mode.ts` — Auto-detection: local mode if `SHANNON_LOCAL=1` env var is set
 - `apps/cli/src/docker.ts` — Compose lifecycle, image pull/build, ephemeral `docker run` worker spawning
 - `apps/cli/src/home.ts` — State directory management (`~/.shannon/` for npx, `./` for local)
@@ -108,7 +109,7 @@ Published as `@keygraph/shannon` on npm. Contains only Docker orchestration logi
 - `apps/cli/src/config/resolver.ts` — Cascading config (npx only): env vars → `~/.shannon/config.toml` (parsed with `smol-toml`)
 - `apps/cli/src/config/writer.ts` — TOML serialization and secure file persistence (0o600)
 - `apps/cli/src/commands/setup.ts` — Interactive TUI wizard (`@clack/prompts`) for provider credential setup (npx only)
-- `apps/cli/src/paths.ts` — Repo/config path resolution (bare name → `./repos/<name>`, or any absolute/relative path)
+- `apps/cli/src/paths.ts` — Repo/config path resolution (any absolute or relative path)
 - `apps/cli/src/version.ts` — Version reporting (npx: `package.json` version; local: `git-<sha>`)
 - `apps/cli/src/tty.ts` — Terminal capability detection: `requireInteractive` guard (fails fast off-TTY instead of hanging on a prompt), `supportsColor` color gating (`NO_COLOR`/`FORCE_COLOR`), and `stdoutIsTerminal` for spinner/cursor output
 - `apps/cli/src/commands/` — Command handlers
@@ -153,10 +154,11 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig
 ### Supporting Systems
 - **Configuration** — YAML configs in `apps/worker/configs/` with JSON Schema validation (`config-schema.json`). Supports auth settings (MFA/TOTP), URL/code rule scoping (`rules.avoid`/`rules.focus`), run-scope steering (`vuln_classes`, `exploit`), free-form `rules_of_engagement`, and post-hoc `report` options (`min_severity`, `min_confidence`, `guidance`, and `sarif` to emit a SARIF 2.1.0 log via `apps/worker/src/services/sarif-renderer.ts`; exploit-only). `code_path` avoid rules are enforced via the `@gotgenes/pi-permission-system` extension: `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` writes a global `path` deny config once per workflow (`apps/worker/src/ai/pi/permission-system.ts:syncPermissionSystemConfig`), and the executor loads the extension when that config is present (`apps/worker/src/ai/pi/pi-executor.ts`), so denies fire across every tool and child `task` session. `vuln_classes`/`exploit` scope is locked into `session.json` on first run; resumes with a different scope fail fast (`persistOrValidateRunScope`). Credential resolution — local mode: env vars → `./.env`; npx mode: env vars → `~/.shannon/config.toml` (via `npx @keygraph/shannon setup`)
 - **Prompts** — Per-phase templates in `apps/worker/prompts/` with variable substitution (`{{TARGET_URL}}`, `{{CONFIG_CONTEXT}}`). Shared partials in `apps/worker/prompts/shared/` via `apps/worker/src/services/prompt-manager.ts`, including `_code-path-rules.txt` (focus/avoid `[FILE]`/`[GLOB]` routing) and `_rules-of-engagement.txt` (free-text engagement rules). When `exploit: false`, `apps/worker/src/services/findings-renderer.ts` deterministically converts each `*_exploitation_queue.json` into a `*_findings.md` for report assembly — no LLM in the loop
-- **Agent Harness (pi)** — Uses the **pi harness** (`@earendil-works/pi-coding-agent`, requires Node ≥ 22.19) via `apps/worker/src/ai/pi/pi-executor.ts` (`runPiPrompt` → `createAgentSession`). Retry is split in `apps/worker/src/ai/pi/retry-settings.ts`: pi's agent-level loop is off so Temporal owns agent restarts, while `provider.maxRetries` stays on — pi reads the `provider` block independently of the `enabled` flag — so transport faults are absorbed in-session rather than costing a full agent re-run. `maxRetryDelayMs` is left at pi's 60s default. One model runs every phase, named by `SHANNON_AI_MODEL=<provider>:<model-id>` (default `anthropic:claude-sonnet-4-6`). `apps/worker/src/ai/models.ts` parses the spec — splitting on the **first** colon only, so Bedrock IDs keep theirs — and resolves it through pi's `ModelRuntime`. pi ships the `CredentialStore` interface but no in-memory implementation (its own reads `auth.json` from disk), so `RuntimeCredentialStore` in that file supplies one: credentials arrive as env vars in an ephemeral container and must never touch disk. `createModelRuntime(providerId, apiKey)` builds the runtime; `allowModelNetwork` stays at its default `false` so a scan never blocks on a catalog refresh. `resolveModelSelection()` is **async** because `ModelRuntime.create()` is. Supported providers (all pi-ai provider ids): `anthropic`, `openai`, `xai`, `amazon-bedrock`. Each provider's API key env var is declared once in `PROVIDER_API_KEY_ENV` — Shannon uses each vendor's own variable name (`OPENAI_API_KEY`, `XAI_API_KEY`, …), never an invented one; Bedrock's entry is `AWS_BEARER_TOKEN_BEDROCK`, paired with `AWS_REGION`, which preflight requires separately as provider config rather than a credential. `SHANNON_AI_BASE_URL` overrides the endpoint for any provider (proxies/gateways); the credential is unchanged. `pointAtGateway` (`apps/worker/src/ai/models.ts`) applies the one dialect change: behind a base URL, `openai` follows `SHANNON_AI_OPENAI_FORMAT` (`chat-completions` default, or `responses`). On `chat-completions` it switches the API to `openai-completions` and drops the catalogue's Responses-shaped `compat` block so pi's `detectCompat` derives completions settings; on `responses` the descriptor is unchanged but for the endpoint. `resolveGatewayFormat` rejects the variable when the provider is not `openai` or no base URL is set, since it cannot take effect there. All other providers keep their API. The CLI mirrors the accepted values in `apps/cli/src/model-spec.ts`, forwards the variable in `COMMON_FORWARD_VARS`, and maps it to `openai.format` in config.toml. `buildEnvFlags` forwards only the selected provider's credential into the worker container. The CLI mirrors the parse rule and the provider/credential tables in `apps/cli/src/model-spec.ts` (it cannot import from the worker package); the two must stay in sync. pi ships no JSON-schema output or `Task`/`TodoWrite` built-ins, so structured queues are captured via a `submit_exploitation_queue` custom tool (`apps/worker/src/ai/queue-schemas.ts`), and `task` (child sessions scoped to `read`, `grep`, `find`, `ls`, `write`, and `bash` — no nested `task` or collector tools; `CHILD_TOOLS` in `apps/worker/src/ai/pi/task-tool.ts`) + `todo_write` (`apps/worker/src/ai/pi/session-tools.ts`) are provided as custom tools; the per-phase collectors are pi custom tools (TypeBox `defineTool` in `apps/worker/src/collectors/`). Shannon sets no thinking configuration at all — no `thinkingLevel` is passed to any `createAgentSession` call, so pi's own default applies. There is no adaptive-thinking support and no `CLAUDE_ADAPTIVE_THINKING` / `core.adaptive_thinking` setting. Browser automation via `playwright-cli` with session isolation (`-s=<session>`). TOTP generation via `generate-totp` CLI tool. Login flow template at `apps/worker/prompts/shared/login-instructions.txt` supports form, SSO, API, and basic auth. On authenticated whitebox scans, the `validate-authentication` preflight performs the single real login and saves the browser session to `auth-state.json` in the per-session audit directory (path from `authStateFile()` in `apps/worker/src/audit/utils.ts`, derived from `generateAuditPath()`). The validation activity (`apps/worker/src/services/validate-authentication.ts`) removes any stale file from a prior run before the agent runs and verifies the file parses and contains cookies or storage before the preflight is marked complete; `logWorkflowComplete` deletes it when the workflow ends so authenticated cookies don't sit on disk between scans. Agent prompts opt in to session reuse by `@include(shared/_shared-session.txt)` before their `<login_instructions>` block — the partial restores the session and falls through to the full login flow if verification fails. `vuln-auth`/`exploit-auth` omit the include and own their own login
-- **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. The run directory's top level holds only the human-facing report (`Security-Assessment-Report.md`, `FINAL_REPORT_FILENAME` in `apps/worker/src/paths.ts`); everything else — deliverables, per-agent logs, prompts, `session.json`, `workflow.log`, and browser artifacts — is nested under a hidden `.shannon/` internals dir (`INTERNAL_DIR`) so a customer sees only the report. Audit path helpers route through `generateInternalPath` (`apps/worker/src/audit/utils.ts`); the CLI nests the overlay backing dirs under the same `.shannon/` (`apps/cli/src/docker.ts`, `start.ts`). `session.json`/`workflow.log` reads use dual-read resolvers (`resolveSessionJsonPath`, `resolveRunFile`) that prefer `.shannon/` and fall back to the legacy run-root layout, so pre-restructure workspaces stay listable (`workspaces`/`logs`) without migration. Resuming a pre-restructure workspace upgrades it in place first: `migrateLegacyWorkspaceLayout` (`apps/cli/src/commands/start.ts`) renames the flat deliverables/logs/session entries into `.shannon/` (carrying the deliverables `.git` along) before the overlay dirs are mounted, so resume finds the old checkpoints instead of re-running every agent. The report is surfaced by copying the assembled `comprehensive_security_assessment_report.md` from the deliverables dir to the run root (`copyReportToRunRoot` in `apps/worker/src/services/reporting.ts`). WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive
+- **Agent Harness (pi)** — Uses the **pi harness** (`@earendil-works/pi-coding-agent`, requires Node ≥ 22.19) via `apps/worker/src/ai/pi/pi-executor.ts` (`runPiPrompt` → `createAgentSession`). Retry is split in `apps/worker/src/ai/pi/retry-settings.ts`: pi's agent-level loop is off so Temporal owns agent restarts, while `provider.maxRetries` stays on — pi reads the `provider` block independently of the `enabled` flag — so transport faults are absorbed in-session rather than costing a full agent re-run. `maxRetryDelayMs` is left at pi's 60s default. One model runs every phase, named by `SHANNON_AI_MODEL=<provider>:<model-id>` (default `anthropic:claude-sonnet-4-6`). `apps/worker/src/ai/models.ts` parses the spec — splitting on the **first** colon only, so Bedrock IDs keep theirs — and resolves it through pi's `ModelRuntime`. pi ships the `CredentialStore` interface but no in-memory implementation (its own reads `auth.json` from disk), so `RuntimeCredentialStore` in that file supplies one: credentials arrive as env vars in an ephemeral container and must never touch disk. `createModelRuntime(providerId, apiKey)` builds the runtime; `allowModelNetwork` stays at its default `false` so a scan never blocks on a catalog refresh. `resolveModelSelection()` is **async** because `ModelRuntime.create()` is. Any pi-ai provider id is accepted — `parseModelSpec` no longer rejects against a hardcoded list, so pi's registry is the authority (an unknown provider/model surfaces as a clear "not found in pi registry" error at preflight, which points to the browsable catalogue at `pi.dev/models` — `PI_CATALOG_URL` in `apps/worker/src/ai/models.ts`, appended to the not-found errors and shown in the setup wizard's "Other provider" hint). Four providers are **curated** (`CURATED_PROVIDERS`: `anthropic`, `openai`, `xai`, `amazon-bedrock`) with their own credential variables, config sections, and setup flows; each provider's API key env var is declared once in `PROVIDER_API_KEY_ENV` — Shannon uses each vendor's own variable name (`OPENAI_API_KEY`, `XAI_API_KEY`, …), never an invented one; Bedrock's entry is `AWS_BEARER_TOKEN_BEDROCK`, paired with `AWS_REGION`, which preflight requires separately as provider config rather than a credential. Any other provider uses the **generic** credential path: `SHANNON_AI_API_KEY` (`GENERIC_API_KEY_ENV`) supplies the key for any provider whose credential is a plain API key. Curated providers' own variables take precedence over it, and it also works as a fallback for them — Bedrock is the sole exception (it authenticates through its AWS_ variables, so the generic key never stands in for it). The CLI forwards `SHANNON_AI_API_KEY` in `COMMON_FORWARD_VARS` (it is provider-neutral, binding to whatever `SHANNON_AI_MODEL` names, so the "only one provider configured" guard counts only named credentials), and stores it under a generic `[provider]` config.toml section (`provider.api_key`). `npx @keygraph/shannon setup` exposes this as the "Other provider" option: free-text provider id + model id + key (a curated provider id is rejected there, since it has its own option). `SHANNON_AI_BASE_URL` overrides the endpoint for any provider (proxies/gateways); the credential is unchanged. `pointAtGateway` (`apps/worker/src/ai/models.ts`) applies the one dialect change: behind a base URL, `openai` follows `SHANNON_AI_OPENAI_FORMAT` (`chat-completions` default, or `responses`). On `chat-completions` it switches the API to `openai-completions` and drops the catalogue's Responses-shaped `compat` block so pi's `detectCompat` derives completions settings; on `responses` the descriptor is unchanged but for the endpoint. `resolveGatewayFormat` rejects the variable when the provider is not `openai` or no base URL is set, since it cannot take effect there. All other providers keep their API. The CLI mirrors the accepted values in `apps/cli/src/model-spec.ts`, forwards the variable in `COMMON_FORWARD_VARS`, and maps it to `openai.format` in config.toml. `buildEnvFlags` forwards only the selected provider's credential into the worker container. The CLI mirrors the parse rule and the provider/credential tables in `apps/cli/src/model-spec.ts` (it cannot import from the worker package); the two must stay in sync. pi ships no JSON-schema output or `Task`/`TodoWrite` built-ins, so structured queues are captured via a `submit_exploitation_queue` custom tool (`apps/worker/src/ai/queue-schemas.ts`), and `task` (child sessions scoped to `read`, `grep`, `find`, `ls`, `write`, and `bash` — no nested `task` or collector tools; `CHILD_TOOLS` in `apps/worker/src/ai/pi/task-tool.ts`) + `todo_write` (`apps/worker/src/ai/pi/session-tools.ts`) are provided as custom tools; the per-phase collectors are pi custom tools (TypeBox `defineTool` in `apps/worker/src/collectors/`). Shannon sets no thinking configuration at all — no `thinkingLevel` is passed to any `createAgentSession` call, so pi's own default applies. There Line truncated
+- **Pi Credential Reuse** — `SHANNON_USE_PI_AUTH=1` opts into reusing the host's Pi login, including an `openai-codex` ChatGPT Plus/Pro subscription selected with `SHANNON_AI_MODEL=openai-codex:<model-id>`. `apps/cli/src/env.ts` requires `~/.pi/agent/auth.json`; `start.ts` passes its path to `spawnWorker`, which mounts only that file read-write at `/tmp/.pi/agent/auth.json`. The flag itself is not forwarded: the worker detects the file with `piAuthPresent()` and passes its path to `ModelRuntime.create`. CLI and worker API-key presence checks are skipped on this path, but the normal preflight model probe still validates the credential. The image and UID-remapping entrypoint keep `/tmp/.pi/agent` owned by `pentest` so adjacent Pi/Shannon configuration remains writable. Refreshed OAuth state is persisted to the host for subsequent scans.
+- **Audit System** — Crash-safe append-only logging in `workspaces/{hostname}_{sessionId}/`. The run directory's top level holds the human-facing report in both formats (`Security-Assessment-Report.pdf` and `Security-Assessment-Report.md`, `FINAL_REPORT_PDF_FILENAME`/`FINAL_REPORT_MD_FILENAME` in `apps/worker/src/paths.ts`); everything else — deliverables, per-agent logs, prompts, `session.json`, `workflow.log`, and browser artifacts — is nested under a hidden `.shannon/` internals dir (`INTERNAL_DIR`) so a customer sees only the report. Audit path helpers route through `generateInternalPath` (`apps/worker/src/audit/utils.ts`); the CLI nests the overlay backing dirs under the same `.shannon/` (`apps/cli/src/docker.ts`, `start.ts`). `session.json`/`workflow.log` reads use dual-read resolvers (`resolveSessionJsonPath`, `resolveRunFile`) that prefer `.shannon/` and fall back to the legacy run-root layout, so pre-restructure workspaces stay listable (`workspaces`/`logs`) without migration. Resuming a pre-restructure workspace upgrades it in place first: `migrateLegacyWorkspaceLayout` (`apps/cli/src/commands/start.ts`) renames the flat deliverables/logs/session entries into `.shannon/` (carrying the deliverables `.git` along) before the overlay dirs are mounted, so resume finds the old checkpoints instead of re-running every agent. The report agent writes structured findings to `report.json`, from which `report-renderer.ts` renders the assembled markdown and `report-json-adapter.ts` produces the Typst-shaped JSON that `pdf-renderer.ts` compiles into `comprehensive_security_assessment_report.pdf` using the bundled `apps/worker/templates/typst/report.typ` template (the `typst` binary is installed in the worker image). `copyReportToRunRoot` (`apps/worker/src/services/reporting.ts`) surfaces both the PDF and the markdown to the run root as `Security-Assessment-Report.pdf` and `Security-Assessment-Report.md`; the deliverables-dir copies remain as the git-checkpointed sources. PDF compilation is best-effort — a failure is logged and the run still completes. WorkflowLogger (`apps/worker/src/audit/workflow-logger.ts`) provides unified human-readable per-workflow logs, backed by LogStream (`apps/worker/src/audit/log-stream.ts`) shared stream primitive
 - **Deliverables** — Saved to `.shannon/deliverables/` in the target repo via the `save-deliverable` CLI script (`apps/worker/src/scripts/save-deliverable.ts`)
-- **Workspaces & Resume** — Named workspaces via `-w <name>` or auto-named from URL+timestamp. Resume detects completed agents via `session.json`. `loadResumeState()` in `apps/worker/src/temporal/activities.ts` validates deliverable existence, restores git checkpoints, and cleans up incomplete deliverables. Workspace listing via `apps/worker/src/temporal/workspaces.ts`
+- **Workspaces & Resume** — Named workspaces via `-w <name>` or auto-named from URL+timestamp. Resume detects completed agents via `session.json`. `loadResumeState()` in `apps/worker/src/temporal/activities.ts` validates deliverable existence, restores git checkpoints, and cleans up incomplete deliverables
 
 ## Development Notes
 
@@ -246,9 +248,9 @@ Package managers are configured with a minimum release age (7 days). Requires pn
 
 ## Troubleshooting
 
-- **"Repository not found"** — Pass a bare name (`-r my-repo`) for `./repos/my-repo`, or a path (`-r /path/to/repo`) for any directory
+- **"Repository not found"** — Pass a path to the target repo (`-r /path/to/repo` or `-r ./my-repo`)
 - **"Temporal not ready"** — Wait for health check or `docker compose logs temporal`
 - **Worker not processing** — Check `docker ps --filter "name=shannon-worker-"`
-- **Reset state** — `./shannon stop --clean`
+- **Reset state** — `./shannon reset`
 - **Local apps unreachable** — Use `host.docker.internal` instead of `localhost`
 - **Container permissions** — On Linux, may need `sudo` for docker commands

Dockerfile

@@ -52,6 +52,8 @@ RUN apk update && apk add --no-cache \
     curl \
     ca-certificates \
     shadow \
+    # Typst tarball decompression
+    xz \
     # Language runtimes (minimal)
     nodejs-22 \
     npm \
@@ -73,6 +75,22 @@ RUN apk update && apk add --no-cache \
     # Font rendering
     fontconfig
 
+# Install Typst (report PDF compilation)
+ARG TYPST_VERSION=0.14.2
+RUN case "$(uname -m)" in \
+      x86_64) TYPST_ARCH=x86_64-unknown-linux-musl ;; \
+      aarch64) TYPST_ARCH=aarch64-unknown-linux-musl ;; \
+      *) echo "unsupported arch $(uname -m)" && exit 1 ;; \
+    esac && \
+    mkdir -p /tmp/typst-dl /usr/local/bin && cd /tmp/typst-dl && \
+    curl -fsSL "https://github.com/typst/typst/releases/download/v${TYPST_VERSION}/typst-${TYPST_ARCH}.tar.xz" -o typst.tar.xz && \
+    xz -d typst.tar.xz && \
+    tar -xf typst.tar && \
+    mv "typst-${TYPST_ARCH}/typst" /usr/local/bin/typst && \
+    chmod +x /usr/local/bin/typst && \
+    cd / && rm -rf /tmp/typst-dl && \
+    typst --version
+
 # Create non-root user
 RUN addgroup -g 1001 pentest && \
     adduser -u 1001 -G pentest -s /bin/bash -D pentest
@@ -107,12 +125,12 @@ RUN ln -s /app/apps/worker/dist/scripts/save-deliverable.js /usr/local/bin/save-
 
 # Create directories for session data and ensure proper permissions
 RUN mkdir -p /app/sessions /app/repos /app/workspaces && \
-    mkdir -p /tmp/.cache /tmp/.config /tmp/.npm && \
+    mkdir -p /tmp/.cache /tmp/.config /tmp/.npm /tmp/.pi/agent && \
     chmod 777 /app && \
     chmod 777 /tmp/.cache && \
     chmod 777 /tmp/.config && \
     chmod 777 /tmp/.npm && \
-    chown -R pentest:pentest /app /tmp/.claude
+    chown -R pentest:pentest /app /tmp/.claude /tmp/.pi
 
 COPY entrypoint.sh /app/entrypoint.sh
 RUN chmod +x /app/entrypoint.sh

README.md

@@ -1,3 +1,6 @@
+> [!NOTE]
+> **[Shannon 2.0 is officially here](https://github.com/KeygraphHQ/shannon/discussions/405)**
+
 <div align="center">
 
 <img src="./assets/github-banner.png" alt="Shannon - AI Pentester by Keygraph" width="100%">
@@ -6,7 +9,7 @@
 
 <a href="https://trendshift.io/repositories/15604" target="_blank"><img src="https://trendshift.io/api/badge/repositories/15604" alt="KeygraphHQ%2Fshannon | Trendshift" style="width: 250px; height: 55px;" width="250" height="55"/></a>
 
-Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
+Shannon is an autonomous, AI pentester for web applications and APIs. <br />
 It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production.
 
 **This repository is Shannon Open Source: the full agent, run locally from your command line.**
@@ -32,13 +35,13 @@ It analyzes your source code, identifies attack paths, and executes real exploit
 - [Architecture](#architecture)
 - [Documentation](#documentation)
 - [Safety, Scope, and Limitations](#safety-scope-and-limitations)
-- [License and Enterprise Licensing](#license-and-enterprise-licensing)
+- [License](#license)
 - [About Keygraph](#about-keygraph)
 - [Community and Support](#community-and-support)
 
 ## What is Shannon?
 
-Shannon is an autonomous AI pentester developed by [Keygraph](https://keygraph.io). It performs white-box security testing of web applications and their underlying APIs by combining source-code analysis with live exploitation.
+Shannon is an autonomous AI pentester developed by [Keygraph](https://keygraph.io). It performs security testing of web applications and their underlying APIs by combining source-code analysis with live exploitation.
 
 Shannon analyzes your web application's source code to identify potential attack vectors, then uses browser automation and command-line tools to execute real exploits against the running application and its APIs. Only vulnerabilities with a working proof-of-concept are included in the final report.
 
@@ -70,7 +73,7 @@ Sample penetration test reports from intentionally vulnerable applications, prod
 
 - **Docker**: required for the worker container.
 - **Node.js 18+**: required for the recommended `npx` workflow.
-- **AI provider credentials**: Anthropic, OpenAI, xAI, or AWS Bedrock. Claude models are recommended. Gateway and proxy setups are documented separately.
+- **AI provider credentials**: Anthropic, OpenAI, xAI, or AWS Bedrock - or [any other provider](docs/ai-providers.md#any-other-provider). Claude models are recommended. For suggested model IDs per provider, plus gateways and custom base URLs, see [AI providers](docs/ai-providers.md#suggested-models).
 - **Cyber safeguards cleared with your provider**: Anthropic and OpenAI apply real-time safeguards to cyber-security workloads, which can interrupt a scan mid-run. Complete their guidance for legitimate security testers before your first run - see [AI providers](docs/ai-providers.md#cyber-safeguards-do-this-before-your-first-scan).
 
 ### Run Shannon
@@ -91,7 +94,10 @@ Shannon pulls the worker image from Docker Hub, starts the required local infras
 For source builds, authenticated scans, provider-specific setup, and platform notes, see [Documentation](#documentation).
 
 > [!TIP]
-> **Prefer to run on your Claude Code subscription instead of API credits?** The [`shannon-v1`](https://github.com/KeygraphHQ/shannon/tree/shannon-v1) branch is the last release built on the Claude Agent SDK, so it accepts a Claude Code OAuth token. Generate one with `claude setup-token`, then run `npx @keygraph/shannon@1.9.0 setup` and pick **OAuth Token**. Pentests then cost nothing beyond your existing subscription.
+> **Prefer to use a subscription instead of API credits?**
+>
+> - **OpenAI Codex:** The latest version of Shannon supports ChatGPT Plus and Pro subscriptions. Follow the [OpenAI Codex subscription setup guide](docs/ai-providers.md#openai-codex-chatgpt-pluspro-subscription) to get started.
+> - **Claude Code:** The latest version of Shannon does not support Claude Code subscriptions. Follow the [Claude Code subscription setup guide](docs/ai-providers.md#claude-code-subscription) to use version `1.9.0`, which is the final release built on the Claude Agent SDK.
 
 ## Key Capabilities
 
@@ -187,7 +193,7 @@ Use these guides for operational detail:
 | --- | --- |
 | [Source build and CLI commands](docs/development.md) | Cloning, building, common commands, output paths, and local development. |
 | [Configuration](docs/configuration.md) | Authenticated testing, login flows, rules of engagement, and report filters. |
-| [AI providers](docs/ai-providers.md) | Selecting the model, the supported providers (Anthropic, OpenAI, xAI, AWS Bedrock), and custom gateways. |
+| [AI providers](docs/ai-providers.md) | Selecting the model, the supported providers (Anthropic, OpenAI, xAI, AWS Bedrock, and any other Pi-supported provider), and custom gateways. |
 | [Platforms and networking](docs/platforms.md) | Windows/WSL2, Linux, macOS, Docker networking, local apps, and custom hostnames. |
 | [Workspaces and resuming](docs/workspaces.md) | Naming workspaces, resuming interrupted scans, and workspace storage. |
 | [Safety and limitations](docs/safety.md) | Authorized-use requirements, non-production guidance, mutative effects, cost, and model caveats. |
@@ -210,7 +216,7 @@ Important limitations:
 
 Read the full [Safety and limitations](docs/safety.md) guide before running Shannon in a new environment.
 
-## License and Enterprise Licensing
+## License
 
 Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](LICENSE).
 

apps/cli/package.json

@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.1.0",
+    "@temporalio/client": "^1.11.0",
     "chokidar": "^5.0.0",
     "dotenv": "^17.3.1",
     "smol-toml": "^1.6.1"

apps/cli/src/args.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared argument parsing for CLI commands.
+ *
+ * Every command declares which boolean flags, value options, and positionals it
+ * accepts; `parseArgs` resolves aliases, rejects anything unrecognized, and hands
+ * back a typed result. This centralizes the common flags (notably `--yes`/`-y`) so
+ * each command no longer re-hardcodes `args.includes('--yes')`, and it makes
+ * unknown flags and stray arguments fail loudly instead of being silently ignored.
+ */
+
+import { closestMatch } from './suggest.js';
+
+/** Thrown when argv does not match a command's schema. The dispatcher formats it. */
+export class ArgError extends Error {}
+
+/** Tokens that set the "skip confirmation" flag, declared once for every command. */
+export const YES_FLAGS = ['--yes', '-y'] as const;
+
+export interface ArgSchema {
+  /** Boolean flags: result key -> accepted tokens (canonical plus any aliases). */
+  readonly booleans?: Record<string, readonly string[]>;
+  /** Value-taking options: result key -> accepted tokens. */
+  readonly values?: Record<string, readonly string[]>;
+  /** Maximum positional arguments allowed. Defaults to 0. */
+  readonly maxPositionals?: number;
+  /** Extra guidance appended to the error when too many positionals are given. */
+  readonly positionalHint?: string;
+}
+
+export interface ParsedArgs {
+  readonly flags: Record<string, boolean>;
+  readonly values: Record<string, string>;
+  readonly positionals: readonly string[];
+}
+
+/** Build a token -> result-key lookup from a schema section. */
+function indexTokens(section: Record<string, readonly string[]>): Map<string, string> {
+  const byToken = new Map<string, string>();
+  for (const [key, tokens] of Object.entries(section)) {
+    for (const token of tokens) {
+      byToken.set(token, key);
+    }
+  }
+  return byToken;
+}
+
+export function parseArgs(argv: readonly string[], schema: ArgSchema): ParsedArgs {
+  const booleanByToken = indexTokens(schema.booleans ?? {});
+  const valueByToken = indexTokens(schema.values ?? {});
+  const maxPositionals = schema.maxPositionals ?? 0;
+
+  const flags: Record<string, boolean> = {};
+  const values: Record<string, string> = {};
+  const positionals: string[] = [];
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === undefined) {
+      continue;
+    }
+
+    const equalsIndex = arg.startsWith('--') ? arg.indexOf('=') : -1;
+    const token = equalsIndex === -1 ? arg : arg.slice(0, equalsIndex);
+    const inlineValue = equalsIndex === -1 ? undefined : arg.slice(equalsIndex + 1);
+
+    const booleanKey = booleanByToken.get(token);
+    if (booleanKey !== undefined) {
+      if (inlineValue !== undefined) {
+        throw new ArgError(`Flag ${token} does not take a value`);
+      }
+      flags[booleanKey] = true;
+      continue;
+    }
+
+    const valueKey = valueByToken.get(token);
+    if (valueKey !== undefined) {
+      if (inlineValue !== undefined) {
+        values[valueKey] = inlineValue;
+        continue;
+      }
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('-')) {
+        throw new ArgError(`Option ${token} requires a value`);
+      }
+      values[valueKey] = next;
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith('-')) {
+      const suggestion = closestMatch(token, [...booleanByToken.keys(), ...valueByToken.keys()]);
+      const hint = suggestion ? `\nDid you mean '${suggestion}'?` : '';
+      throw new ArgError(`Unknown option: ${token}${hint}`);
+    }
+
+    positionals.push(arg);
+  }
+
+  if (positionals.length > maxPositionals) {
+    const extra = positionals[maxPositionals];
+    const hint = schema.positionalHint ? `\n${schema.positionalHint}` : '';
+    throw new ArgError(`Unexpected argument: ${extra}${hint}`);
+  }
+
+  return { flags, values, positionals };
+}

apps/cli/src/colors.ts

@@ -0,0 +1,34 @@
+/**
+ * ANSI color and style escapes — the single source for the CLI's palette.
+ *
+ * Codes are plain constants; callers decide whether to emit them via `paint`
+ * (wrap-and-reset) or `gate` (prefix-or-empty), gating on `supportsColor()` from
+ * `tty.ts`. Cursor-control escapes live with their sole consumer, not here — this
+ * module is color only.
+ */
+
+export const RESET = '\x1b[0m';
+
+/** Shannon brand gold — the running/completed accent, shared with the splash logo. */
+export const GOLD = '\x1b[38;2;244;197;66m';
+
+export const BOLD = '\x1b[1m';
+export const RED = '\x1b[31m';
+export const YELLOW = '\x1b[33m';
+export const DIM = '\x1b[90m';
+
+// The splash logo uses bolder variants of cyan/white/yellow than the progress tree.
+export const CYAN = '\x1b[36;1m';
+export const WHITE = '\x1b[1;37m';
+export const GRAY = '\x1b[0;37m';
+export const BOLD_YELLOW = '\x1b[1;33m';
+
+/** Wrap `text` in `code` and reset, or return it unchanged when color is off. */
+export function paint(text: string, code: string, enabled: boolean): string {
+  return enabled ? `${code}${text}${RESET}` : text;
+}
+
+/** A style code when color is on, or an empty string when off — for templates that interleave prefixes directly. */
+export function gate(code: string, enabled: boolean): string {
+  return enabled ? code : '';
+}

apps/cli/src/commands/build.ts

@@ -3,13 +3,17 @@
  * Requires a clone (Dockerfile in the working directory).
  */
 
-import { buildImage, canBuildImage } from '../docker.js';
+import { buildImage, canBuildImage, ensureDocker } from '../docker.js';
+import { fail } from '../errors.js';
 
 export function build(noCache: boolean, version: string): void {
+  ensureDocker();
+
   if (!canBuildImage()) {
-    console.error('ERROR: Build is only available when running from the Shannon repository');
-    console.error('  (Dockerfile not found in current directory)');
-    process.exit(1);
+    fail(
+      'Build is only available when running from the Shannon repository',
+      '  (Dockerfile not found in current directory)',
+    );
   }
 
   buildImage(noCache, version);

apps/cli/src/commands/logs.ts

@@ -8,8 +8,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { watch } from 'chokidar';
+import { fail } from '../errors.js';
 import { getWorkspacesDir } from '../home.js';
 import { resolveRunFile } from '../paths.js';
+import { stdoutIsTerminal } from '../tty.js';
 
 // Match the exact line the worker writes — anchored to prevent false positives from agent output
 const COMPLETION_PATTERN = /^Scan (COMPLETED|FAILED)$/m;
@@ -28,7 +30,7 @@ function readRange(filePath: string, start: number, end: number): string {
 }
 
 /** Resolve a workspace ID to its workflow.log path, or exit with an error. */
-function resolveLogFile(workspaceId: string): string {
+export function resolveLogFile(workspaceId: string): string {
   const workspacesDir = getWorkspacesDir();
 
   // 1. Direct match
@@ -49,59 +51,71 @@ function resolveLogFile(workspaceId: string): string {
     if (fs.existsSync(namedPath)) return namedPath;
   }
 
-  console.error(`ERROR: No scan found named: ${workspaceId}`);
-  console.error('');
-  console.error('Possible causes:');
-  console.error("  - The scan hasn't started yet");
-  console.error('  - The workspace name is incorrect');
-  console.error('');
-  console.error('Check the dashboard at http://localhost:8233 for scan details');
-  process.exit(1);
+  fail(
+    `No scan found named: ${workspaceId}`,
+    '',
+    'Possible causes:',
+    "  - The scan hasn't started yet",
+    '  - The workspace name is incorrect',
+    '',
+    'Check the dashboard at http://localhost:8233 for scan details',
+  );
+}
+
+/**
+ * Tail a scan's log until it reports completion, resolving when the completion marker appears
+ * (or the file is gone, or Ctrl-C stops it). Never exits the process, so the caller decides what
+ * happens next: plain `logs` exits 0; `start --follow` reads the workflow outcome first.
+ */
+export function tailUntilComplete(logFile: string): Promise<void> {
+  return new Promise((resolve) => {
+    let position = 0;
+
+    /**
+     * Output any new content appended since the last read.
+     * Returns true when the workflow completion marker is detected.
+     */
+    function flush(): boolean {
+      try {
+        const { size } = fs.statSync(logFile);
+        if (size <= position) return false;
+
+        const data = readRange(logFile, position, size);
+        process.stdout.write(data);
+        position = size;
+
+        return COMPLETION_PATTERN.test(data);
+      } catch {
+        // File deleted or unreadable — treat as done
+        return true;
+      }
+    }
+
+    // 1. Output existing content
+    if (flush()) {
+      resolve();
+      return;
+    }
+
+    // 2. Watch for appended content via chokidar
+    const watcher = watch(logFile, { persistent: true });
+
+    const stop = (): void => {
+      watcher.close().finally(() => resolve());
+      // Safety net — resolve anyway if watcher.close() stalls
+      setTimeout(() => resolve(), 1000).unref();
+    };
+
+    watcher.on('change', () => {
+      if (flush()) stop();
+    });
+
+    process.on('SIGINT', stop);
+  });
 }
 
 export function logs(workspaceId: string): void {
   const logFile = resolveLogFile(workspaceId);
-  let position = 0;
-
-  /**
-   * Output any new content appended since the last read.
-   * Returns true when the workflow completion marker is detected.
-   */
-  function flush(): boolean {
-    try {
-      const { size } = fs.statSync(logFile);
-      if (size <= position) return false;
-
-      const data = readRange(logFile, position, size);
-      process.stdout.write(data);
-      position = size;
-
-      return COMPLETION_PATTERN.test(data);
-    } catch {
-      // File deleted or unreadable — treat as done
-      return true;
-    }
-  }
-
-  console.log(`Tailing scan log: ${logFile}`);
-
-  // 1. Output existing content
-  if (flush()) {
-    process.exit(0);
-  }
-
-  // 2. Watch for appended content via chokidar
-  const watcher = watch(logFile, { persistent: true });
-
-  const shutdown = (): void => {
-    watcher.close().finally(() => process.exit(0));
-    // Safety net — force exit if watcher.close() stalls
-    setTimeout(() => process.exit(0), 1000).unref();
-  };
-
-  watcher.on('change', () => {
-    if (flush()) shutdown();
-  });
-
-  process.on('SIGINT', shutdown);
+  console.error(stdoutIsTerminal() ? `Tailing scan log: ${logFile}` : 'Tailing scan log');
+  tailUntilComplete(logFile).finally(() => process.exit(0));
 }

apps/cli/src/commands/reset.ts

@@ -0,0 +1,26 @@
+/**
+ * `shannon reset` command — stop everything and wipe all Temporal data and volumes,
+ * returning the machine to a clean slate. The destructive counterpart to `stop`.
+ */
+
+import * as p from '@clack/prompts';
+import { confirmByTyping } from '../confirm.js';
+import { ensureDocker, runningContainers, stopContainers, stopInfra, WORKER_FILTER } from '../docker.js';
+
+export async function reset(): Promise<void> {
+  ensureDocker();
+
+  console.log('This will stop all running scans and permanently remove all Temporal data and volumes.');
+  await confirmByTyping('reset', 'confirm');
+
+  const spinner = p.spinner();
+  spinner.start('Stopping scans');
+  const running = runningContainers(WORKER_FILTER);
+  await stopContainers(running);
+  spinner.stop(
+    running.length > 0 ? `Stopped ${running.length} scan${running.length === 1 ? '' : 's'}` : 'No scans running',
+  );
+
+  await stopInfra(true);
+  console.log('Reset complete.');
+}

apps/cli/src/commands/scans.ts

@@ -0,0 +1,197 @@
+/**
+ * `shannon scans` command — list completed scans and where each report lives.
+ *
+ * A scan counts as completed when it produced a report. The report can live in any of a
+ * few locations depending on the version that ran it, so `findReport` probes them in order
+ * and the first hit is both the completion signal and the link target behind the workspace
+ * name. The date and wall-clock duration come from the run's session.json
+ * (createdAt/completedAt), with the report file's mtime as the date fallback for
+ * runs that lack a recorded time.
+ *
+ * Human-readable by default; `--json` emits the same rows as raw machine values on stdout.
+ *
+ * Filesystem-only (local ./workspaces/ or npx ~/.shannon/workspaces/ via getWorkspacesDir);
+ * no Temporal dependency.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { BOLD, GOLD, paint } from '../colors.js';
+import { getWorkspacesDir } from '../home.js';
+import { commandPrefix } from '../mode.js';
+import { FINAL_REPORT_PDF_FILENAME, INTERNAL_DIR, resolveRunFile } from '../paths.js';
+import { stdoutIsTerminal, supportsColor } from '../tty.js';
+
+/** Assembled report in the deliverables dir. Must match ASSEMBLED_REPORT_FILENAME in the worker package. */
+const ASSEMBLED_REPORT_FILENAME = 'comprehensive_security_assessment_report.md';
+
+/** Run-root markdown surfaced by older versions, before the PDF. Kept so those runs still list. */
+const FINAL_REPORT_MD_FILENAME = 'Security-Assessment-Report.md';
+
+const DELIVERABLES_SUBDIR = 'deliverables';
+
+/** One completed scan; raw values so the table and --json render from one source. */
+interface ScanRow {
+  readonly workspace: string;
+  /** Completion time in ms — sort key and date source. */
+  readonly finishedMs: number;
+  /** Wall-clock duration (completedAt − createdAt) in ms, or null when unknown. */
+  readonly durationMs: number | null;
+  /** Absolute path to the report file — the link target behind the workspace name. */
+  readonly report: string;
+}
+
+/** The --json row shape: raw machine values, one per completed scan. */
+interface JsonRow {
+  readonly workspace: string;
+  readonly finishedAt: string;
+  readonly durationMs: number | null;
+  readonly reportPath: string;
+}
+
+/** Compact wall-clock duration from milliseconds: "47s", "1m 32s", "1h 47m". */
+function formatDuration(ms: number): string {
+  const totalSeconds = Math.round(ms / 1000);
+  if (totalSeconds < 60) {
+    return `${totalSeconds}s`;
+  }
+  const totalMinutes = Math.floor(totalSeconds / 60);
+  if (totalMinutes < 60) {
+    return `${totalMinutes}m ${totalSeconds % 60}s`;
+  }
+  return `${Math.floor(totalMinutes / 60)}h ${totalMinutes % 60}m`;
+}
+
+/**
+ * Wrap `text` in an OSC 8 hyperlink to `url` so a supporting terminal opens it on click,
+ * or return `text` unchanged. Terminals without OSC 8 simply show the text.
+ */
+function hyperlink(text: string, url: string): string {
+  return `\x1b]8;;${url}\x1b\\${text}\x1b]8;;\x1b\\`;
+}
+
+/** First existing report path for a run (newest-surfaced first), or null if it has none. */
+function findReport(runDir: string): string | null {
+  const candidates = [
+    path.join(runDir, FINAL_REPORT_PDF_FILENAME),
+    path.join(runDir, FINAL_REPORT_MD_FILENAME),
+    path.join(runDir, INTERNAL_DIR, DELIVERABLES_SUBDIR, ASSEMBLED_REPORT_FILENAME),
+    path.join(runDir, DELIVERABLES_SUBDIR, ASSEMBLED_REPORT_FILENAME),
+  ];
+
+  for (const candidate of candidates) {
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+interface SessionData {
+  readonly session: { readonly createdAt?: string; readonly completedAt?: string };
+}
+
+/** Read a run's session.json (dual-read across layouts). Missing or unreadable → empty shape. */
+function readSession(runDir: string): SessionData {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(resolveRunFile(runDir, 'session.json'), 'utf8'));
+    return { session: parsed?.session ?? {} };
+  } catch {
+    return { session: {} };
+  }
+}
+
+/** Gather every workspace that has a report, one row each. */
+function collectCompletedScans(workspacesDir: string): ScanRow[] {
+  let entries: fs.Dirent[];
+  try {
+    entries = fs.readdirSync(workspacesDir, { withFileTypes: true });
+  } catch {
+    // Workspaces directory does not exist yet — no scans have ever run.
+    return [];
+  }
+
+  const rows: ScanRow[] = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+
+    const runDir = path.join(workspacesDir, entry.name);
+    const reportPath = findReport(runDir);
+    if (!reportPath) {
+      continue;
+    }
+
+    const { session } = readSession(runDir);
+    const completedMs = Date.parse(session.completedAt ?? '');
+    const createdMs = Date.parse(session.createdAt ?? '');
+    const finishedMs = Number.isNaN(completedMs) ? fs.statSync(reportPath).mtimeMs : completedMs;
+    const durationMs = Number.isNaN(completedMs) || Number.isNaN(createdMs) ? null : completedMs - createdMs;
+
+    rows.push({ workspace: entry.name, finishedMs, durationMs, report: reportPath });
+  }
+  return rows;
+}
+
+function toJsonRow(row: ScanRow): JsonRow {
+  return {
+    workspace: row.workspace,
+    finishedAt: new Date(row.finishedMs).toISOString(),
+    durationMs: row.durationMs,
+    reportPath: row.report,
+  };
+}
+
+/** Print the completed scans as an aligned table with the workspace name linked to its report. */
+function printTable(workspacesDir: string, rows: readonly ScanRow[]): void {
+  if (rows.length === 0) {
+    const prefix = commandPrefix();
+    console.log(`No completed scans yet. Run '${prefix} start -u <url> -r <path>' to begin.`);
+    return;
+  }
+
+  const color = supportsColor();
+  // On a terminal the workspace name is an OSC 8 hyperlink that opens its report; when
+  // piped there is nothing to click, so it prints as plain text.
+  const linkable = stdoutIsTerminal();
+
+  const table = rows.map((row) => ({
+    finished: new Date(row.finishedMs).toISOString().slice(0, 10),
+    duration: row.durationMs === null ? '—' : formatDuration(row.durationMs),
+    workspace: row.workspace,
+    report: row.report,
+  }));
+
+  const dateWidth = Math.max('FINISHED'.length, 'YYYY-MM-DD'.length);
+  const durationWidth = Math.max('DURATION'.length, ...table.map((row) => row.duration.length));
+
+  console.log(`\nCompleted scans in ${workspacesDir}:\n`);
+  const header = `${'FINISHED'.padEnd(dateWidth)}  ${'DURATION'.padEnd(durationWidth)}  WORKSPACE`;
+  console.log(paint(header, BOLD, color));
+
+  for (const row of table) {
+    const finished = row.finished.padEnd(dateWidth);
+    const duration = row.duration.padEnd(durationWidth);
+    const name = paint(row.workspace, GOLD, color);
+    const workspace = linkable ? hyperlink(name, pathToFileURL(row.report).href) : name;
+    console.log(`${finished}  ${duration}  ${workspace}`);
+  }
+  console.log('');
+}
+
+export function scans(opts: { readonly json: boolean }): void {
+  const workspacesDir = getWorkspacesDir();
+  const rows = collectCompletedScans(workspacesDir);
+
+  // Latest on top.
+  rows.sort((a, b) => b.finishedMs - a.finishedMs);
+
+  if (opts.json) {
+    console.log(JSON.stringify(rows.map(toJsonRow), null, 2));
+    return;
+  }
+
+  printTable(workspacesDir, rows);
+}

apps/cli/src/commands/setup.ts

@@ -10,13 +10,16 @@ import os from 'node:os';
 import path from 'node:path';
 import * as p from '@clack/prompts';
 import { type ShannonConfig, saveConfig } from '../config/writer.js';
-import { type OpenAiFormat, type ProviderId, SUPPORTED_PROVIDERS } from '../model-spec.js';
+import { CURATED_PROVIDERS, type CuratedProviderId, isCuratedProvider, type OpenAiFormat } from '../model-spec.js';
+import { displaySplash } from '../splash.js';
 import { requireInteractive } from '../tty.js';
+import { getVersion } from '../version.js';
 
 const SHANNON_HOME = path.join(os.homedir(), '.shannon');
 
 const CUSTOM_MODEL = '__custom__';
 const CUSTOM_BASE_URL = '__custom_base_url__';
+const OTHER_PROVIDER = '__other_provider__';
 
 /**
  * Wire formats reachable through the gateway route. The format picks the provider
@@ -39,28 +42,35 @@ const GATEWAY_DIALECTS: readonly {
   { value: 'openai-responses', label: 'OpenAI Responses', provider: 'openai', format: 'responses' },
 ];
 
-/** Suggested models per provider, best-first. Free-text entry accepts any model in the provider's catalogue. */
-const MODEL_SUGGESTIONS: Readonly<Record<ProviderId, readonly string[]>> = {
+/** Suggested models per curated provider, best-first. Free-text entry accepts any model in the provider's catalogue. */
+const MODEL_SUGGESTIONS: Readonly<Record<CuratedProviderId, readonly string[]>> = {
   anthropic: ['claude-sonnet-4-6', 'claude-opus-4-8', 'claude-opus-4-7', 'claude-haiku-4-5-20251001'],
   openai: ['gpt-5.6-sol', 'gpt-5.5', 'gpt-5.4'],
   xai: ['grok-4.5'],
   'amazon-bedrock': ['us.anthropic.claude-sonnet-4-6', 'us.anthropic.claude-opus-4-8', 'us.anthropic.claude-opus-4-7'],
 };
 
-/** Placeholder shown in the free-text model ID prompt. */
-const MODEL_ID_PLACEHOLDER: Readonly<Record<ProviderId, string>> = {
+/** Placeholder shown in the free-text model ID prompt, per curated provider. */
+const MODEL_ID_PLACEHOLDER: Readonly<Record<CuratedProviderId, string>> = {
   anthropic: 'claude-sonnet-4-6',
   openai: 'gpt-5.6-sol',
   xai: 'grok-4.5',
   'amazon-bedrock': 'us.anthropic.claude-opus-4-8',
 };
 
+/** Model ID placeholder for a provider, absent when the provider is not curated. */
+function modelIdPlaceholder(provider: string): string | undefined {
+  return isCuratedProvider(provider) ? MODEL_ID_PLACEHOLDER[provider] : undefined;
+}
+
 export async function setup(): Promise<void> {
   requireInteractive('setup', 'For non-interactive use, export credentials as env vars (e.g. ANTHROPIC_API_KEY).');
-  p.intro('Shannon Setup');
+  displaySplash(getVersion());
+  p.intro('Setup');
 
   // 1. Select provider. "Custom Base URL" is a route, not a provider — it asks
-  //    which API dialect the gateway speaks and configures that provider.
+  //    which API dialect the gateway speaks and configures that provider. "Other
+  //    provider" reaches any pi-supported provider Shannon does not curate.
   const selected = await p.select({
     message: 'Select your AI provider',
     options: [
@@ -69,14 +79,17 @@ export async function setup(): Promise<void> {
       { value: 'xai' as const, label: 'xAI', hint: 'Grok models' },
       { value: 'amazon-bedrock' as const, label: 'AWS Bedrock', hint: 'Claude models via AWS' },
       { value: CUSTOM_BASE_URL as typeof CUSTOM_BASE_URL, label: 'Custom Base URL', hint: 'your own proxy or gateway' },
+      {
+        value: OTHER_PROVIDER as typeof OTHER_PROVIDER,
+        label: 'Other provider',
+        hint: 'any other Pi-supported provider',
+      },
     ],
   });
   if (p.isCancel(selected)) return cancelAndExit();
 
   // 2. Credentials — and, on the gateway route, the endpoint and its dialect.
-  const gateway = selected === CUSTOM_BASE_URL ? await setupGateway() : undefined;
-  const provider = gateway?.provider ?? (selected as ProviderId);
-  const config = gateway?.config ?? (await setupProvider(provider));
+  const { provider, config, gateway } = await setupSelection(selected);
 
   // 3. The model that runs every phase.
   const modelId = await promptModel(provider);
@@ -95,7 +108,27 @@ export async function setup(): Promise<void> {
   p.outro('Run `npx @keygraph/shannon start` to begin a scan.');
 }
 
-async function setupProvider(provider: ProviderId): Promise<ShannonConfig> {
+interface Selection {
+  provider: string;
+  config: ShannonConfig;
+  gateway?: GatewaySetup;
+}
+
+/** Resolve the provider selection into a provider id and its credential config. */
+async function setupSelection(
+  selected: CuratedProviderId | typeof CUSTOM_BASE_URL | typeof OTHER_PROVIDER,
+): Promise<Selection> {
+  if (selected === CUSTOM_BASE_URL) {
+    const gateway = await setupGateway();
+    return { provider: gateway.provider, config: gateway.config, gateway };
+  }
+  if (selected === OTHER_PROVIDER) {
+    return setupOtherProvider();
+  }
+  return { provider: selected, config: await setupProvider(selected) };
+}
+
+async function setupProvider(provider: CuratedProviderId): Promise<ShannonConfig> {
   switch (provider) {
     case 'amazon-bedrock':
       return setupBedrock();
@@ -108,6 +141,27 @@ async function setupProvider(provider: ProviderId): Promise<ShannonConfig> {
   }
 }
 
+/**
+ * Any pi provider Shannon does not curate. The id is free text — the worker's
+ * preflight validates it — and the key is stored generically as SHANNON_AI_API_KEY.
+ */
+async function setupOtherProvider(): Promise<Selection> {
+  p.log.info('Browse supported providers and models at https://pi.dev/models');
+  const provider = await p.text({
+    message: 'Provider ID',
+    validate: (value) => {
+      const id = value?.trim();
+      if (!id) return 'Provider ID is required';
+      if (isCuratedProvider(id)) return `${id} has its own option.`;
+      return undefined;
+    },
+  });
+  if (p.isCancel(provider)) return cancelAndExit();
+
+  const apiKey = await promptSecret('Enter the API key');
+  return { provider: provider.trim(), config: { provider: { api_key: apiKey } } };
+}
+
 // === Provider Setup Flows ===
 
 async function setupAnthropic(): Promise<ShannonConfig> {
@@ -143,7 +197,7 @@ async function setupBedrock(): Promise<ShannonConfig> {
 }
 
 interface GatewaySetup {
-  provider: ProviderId;
+  provider: CuratedProviderId;
   config: ShannonConfig;
   baseUrl: string;
   format?: OpenAiFormat;
@@ -195,11 +249,11 @@ async function setupGateway(): Promise<GatewaySetup> {
  * Ask for the one model that runs every phase. Providers with suggestions offer a
  * pick list with a free-text escape hatch; the rest go straight to free text.
  */
-async function promptModel(provider: ProviderId): Promise<string> {
-  const suggestions = MODEL_SUGGESTIONS[provider];
+async function promptModel(provider: string): Promise<string> {
+  const suggestions = isCuratedProvider(provider) ? MODEL_SUGGESTIONS[provider] : [];
 
   if (suggestions.length === 0) {
-    return promptModelId(provider, MODEL_ID_PLACEHOLDER[provider]);
+    return promptModelId(provider, modelIdPlaceholder(provider));
   }
 
   const choice = await p.select({
@@ -212,7 +266,7 @@ async function promptModel(provider: ProviderId): Promise<string> {
   if (p.isCancel(choice)) return cancelAndExit();
 
   if (choice === CUSTOM_MODEL) {
-    return promptModelId(provider, MODEL_ID_PLACEHOLDER[provider]);
+    return promptModelId(provider, modelIdPlaceholder(provider));
   }
   return choice as string;
 }
@@ -222,13 +276,13 @@ async function promptModel(provider: ProviderId): Promise<string> {
  * one. Bedrock model IDs carry their own colons (`…-v1:0`), so only a genuine
  * provider id counts as a prefix.
  */
-function conflictingProviderPrefix(provider: ProviderId, value: string): string | undefined {
+function conflictingProviderPrefix(provider: string, value: string): string | undefined {
   const separator = value.indexOf(':');
   if (separator === -1) return undefined;
 
   const head = value.slice(0, separator);
   if (head === provider) return undefined;
-  return (SUPPORTED_PROVIDERS as readonly string[]).includes(head) ? head : undefined;
+  return (CURATED_PROVIDERS as readonly string[]).includes(head) ? head : undefined;
 }
 
 /**
@@ -236,10 +290,10 @@ function conflictingProviderPrefix(provider: ProviderId, value: string): string
  * and the caller pairs it with the provider — pasting a full `<provider>:<model>`
  * spec just has its redundant prefix dropped.
  */
-async function promptModelId(provider: ProviderId, placeholder: string): Promise<string> {
+async function promptModelId(provider: string, placeholder?: string): Promise<string> {
   const modelId = await p.text({
     message: 'Model ID',
-    placeholder,
+    ...(placeholder && { placeholder }),
     validate: (value) => {
       if (!value) return 'Model ID is required';
       const conflicting = conflictingProviderPrefix(provider, value);

apps/cli/src/commands/start.ts

@@ -8,14 +8,27 @@
 import { execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-import { ensureImage, ensureInfra, randomSuffix, spawnWorker } from '../docker.js';
-import { buildEnvFlags, loadEnv, validateCredentials } from '../env.js';
+import { setTimeout as sleep } from 'node:timers/promises';
+import * as p from '@clack/prompts';
+import { ensureDocker, ensureImage, ensureInfra, randomSuffix, spawnWorker } from '../docker.js';
+import { buildEnvFlags, loadEnv, resolveHostPiAuthPath, shouldUsePiAuth, validateCredentials } from '../env.js';
+import { fail } from '../errors.js';
 import { getWorkspacesDir, initHome } from '../home.js';
-import { isLocal } from '../mode.js';
+import { commandPrefix, isLocal } from '../mode.js';
 import { resolveModelSpec } from '../model-spec.js';
-import { FINAL_REPORT_FILENAME, INTERNAL_DIR, resolveConfig, resolveRepo, resolveRunFile } from '../paths.js';
+import {
+  expandHome,
+  FINAL_REPORT_PDF_FILENAME,
+  INTERNAL_DIR,
+  resolveConfig,
+  resolveRepo,
+  resolveRunFile,
+} from '../paths.js';
+import { resolveWorkflowId } from '../session.js';
 import { displaySplash } from '../splash.js';
+import { getTerminalOutcome } from '../temporal-client.js';
 import { stdoutIsTerminal } from '../tty.js';
+import { tailUntilComplete } from './logs.js';
 
 export interface StartArgs {
   url: string;
@@ -24,7 +37,8 @@ export interface StartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  debug: boolean;
+  keepContainer: boolean;
+  follow: boolean;
   version: string;
 }
 
@@ -59,22 +73,29 @@ export async function start(args: StartArgs): Promise<void> {
   // 2. Validate credentials
   const creds = validateCredentials();
   if (!creds.valid) {
-    console.error(`ERROR: ${creds.error}`);
-    process.exit(1);
+    fail(creds.error ?? 'Invalid credentials');
   }
 
   // 3. Resolve paths
   const repo = resolveRepo(args.repo);
   const config = args.config ? resolveConfig(args.config) : undefined;
 
+  // Inputs are valid — show the splash before the Docker/Temporal setup work.
+  displaySplash(isLocal() ? undefined : args.version);
+
   // 4. Ensure workspaces dir is writable by container user (UID 1001)
   const workspacesDir = getWorkspacesDir();
   fs.mkdirSync(workspacesDir, { recursive: true });
   fs.chmodSync(workspacesDir, 0o777);
 
-  // 5. Ensure image (auto-build in dev, pull in npx) and start infra
+  // 5. Ensure Docker and the worker image are available (pull/build prints its own progress).
+  ensureDocker();
   ensureImage(args.version);
-  await ensureInfra();
+
+  // One spinner spans the whole launch: bringing up Temporal and registering the worker.
+  const spinner = p.spinner();
+  spinner.start('Starting scan');
+  await ensureInfra(spinner);
 
   // 6. Generate unique task queue and container name
   const suffix = randomSuffix();
@@ -109,7 +130,7 @@ export async function start(args: StartArgs): Promise<void> {
   fs.mkdirSync(path.join(repo.hostPath, '.playwright'), { recursive: true });
 
   // 10. Resolve output directory
-  const outputDir = args.output ? path.resolve(args.output) : undefined;
+  const outputDir = args.output ? path.resolve(expandHome(args.output)) : undefined;
   if (outputDir) {
     fs.mkdirSync(outputDir, { recursive: true });
   }
@@ -117,10 +138,7 @@ export async function start(args: StartArgs): Promise<void> {
   // 11. Resolve prompts directory (local mode only)
   const promptsDir = isLocal() ? path.resolve('apps/worker/prompts') : undefined;
 
-  // 12. Display splash screen
-  displaySplash(isLocal() ? undefined : args.version);
-
-  // 13. Spawn worker container
+  // 12. Spawn worker container
   const proc = spawnWorker({
     version: args.version,
     url: args.url,
@@ -134,19 +152,18 @@ export async function start(args: StartArgs): Promise<void> {
     ...(outputDir && { outputDir }),
     workspace,
     ...(args.pipelineTesting && { pipelineTesting: true }),
-    ...(args.debug && { debug: true }),
+    ...(args.keepContainer && { keepContainer: true }),
+    ...(shouldUsePiAuth() && { piAuthHostPath: resolveHostPiAuthPath() }),
   });
 
-  // 14. Bail if `docker run -d` itself fails (mount error, image missing, etc.)
+  // Bail if `docker run -d` itself fails (mount error, image missing, etc.)
   const dockerExitCode = await new Promise<number>((resolve) => {
     proc.once('exit', (code) => resolve(code ?? 1));
-    proc.once('error', (err) => {
-      console.error(`Failed to start the scan: ${err.message}`);
-      resolve(1);
-    });
+    proc.once('error', () => resolve(1));
   });
 
   if (dockerExitCode !== 0) {
+    spinner.error('Could not start the scan');
     process.exit(1);
   }
 
@@ -163,64 +180,23 @@ export async function start(args: StartArgs): Promise<void> {
     }
   }
 
-  // Poll for workflow to register in session.json. Off-TTY, skip the dots and
-  // clear-line escape so redirected logs stay clean.
-  const animate = stdoutIsTerminal();
-  process.stdout.write('Waiting for the scan to start...');
-  let workflowId = '';
   let started = false;
-  let attempts = 0;
-  const pollInterval = setInterval(() => {
-    attempts++;
-    if (attempts > 60) {
-      clearInterval(pollInterval);
-      process.stdout.write('\n');
-      console.error('Timed out waiting for the scan to start');
-      process.exit(1);
-    }
 
-    try {
-      const session = JSON.parse(fs.readFileSync(sessionJson, 'utf-8'));
-      const resumeAttempts: { workflowId: string }[] = session.session?.resumeAttempts ?? [];
-
-      // Fresh: session.json appears with originalWorkflowId. Resume: new resumeAttempts entry.
-      const ready = isResume ? resumeAttempts.length > initialResumeCount : !!session.session?.originalWorkflowId;
-
-      if (ready) {
-        clearInterval(pollInterval);
-        started = true;
-
-        // Latest workflow ID: last resume attempt, or originalWorkflowId for fresh scans
-        workflowId = resumeAttempts.at(-1)?.workflowId ?? session.session?.originalWorkflowId ?? '';
-
-        // Clear the waiting line, or just break it off-TTY
-        process.stdout.write(animate ? '\r\x1b[K' : '\n');
-        printInfo(args, workspace, workflowId, repo.hostPath, workspacesDir);
-        return;
-      }
-    } catch {
-      // File doesn't exist yet
-    }
-    if (animate) process.stdout.write('.');
-  }, 2000);
-
-  // Stop the worker container only if it hasn't started yet
+  // Stop the worker only if the scan hasn't registered yet (e.g. Ctrl-C mid-startup).
   let cleaned = false;
   const cleanup = (): void => {
     if (cleaned || started) return;
     cleaned = true;
-    clearInterval(pollInterval);
-    console.log('\nStopping scan...');
+    spinner.stop('Stopping scan');
     try {
       execFileSync('docker', ['stop', containerName], { stdio: 'pipe' });
     } catch {
       // Container may have already exited
     }
-    if (args.debug) {
-      printDebugHint(containerName);
+    if (args.keepContainer) {
+      printPreservedContainerHint(containerName);
     }
   };
-
   process.on('SIGINT', () => {
     cleanup();
     process.exit(0);
@@ -230,9 +206,69 @@ export async function start(args: StartArgs): Promise<void> {
     process.exit(0);
   });
   process.on('exit', cleanup);
+
+  // Poll for the workflow to register in session.json; the spinner resolves once it does.
+  spinner.message('Waiting for the scan to start');
+  for (let attempts = 0; attempts < 60; attempts++) {
+    try {
+      const session = JSON.parse(fs.readFileSync(sessionJson, 'utf-8'));
+      const resumeAttempts: { workflowId: string }[] = session.session?.resumeAttempts ?? [];
+
+      // Fresh: session.json appears with originalWorkflowId. Resume: new resumeAttempts entry.
+      const ready = isResume ? resumeAttempts.length > initialResumeCount : !!session.session?.originalWorkflowId;
+
+      if (ready) {
+        started = true;
+        spinner.stop(`Scan started — ${workspace}`);
+        printInfo(args, workspace, repo.hostPath, workspacesDir);
+        if (args.follow) {
+          await followScan(workspace, workspacesDir);
+        }
+        return;
+      }
+    } catch {
+      // File doesn't exist yet
+    }
+    await sleep(2000);
+  }
+
+  spinner.error('Timed out waiting for the scan to start');
+  process.exit(1);
 }
 
-function printDebugHint(containerName: string): void {
+/**
+ * Follow a just-started scan (for `--follow`, aimed at CI): stream its log to completion, then
+ * exit on the workflow outcome — 0 if the assessment ran, 1 if the scan failed. That tracks
+ * whether the pipeline ran, not whether vulnerabilities were found.
+ */
+async function followScan(workspace: string, workspacesDir: string): Promise<never> {
+  const logFile = resolveRunFile(path.join(workspacesDir, workspace), 'workflow.log');
+
+  // The worker creates workflow.log as it starts; wait briefly so the first read doesn't
+  // mistake a not-yet-created file for an already-finished scan.
+  for (let attempts = 0; attempts < 30 && !fs.existsSync(logFile); attempts++) {
+    await sleep(1000);
+  }
+
+  if (stdoutIsTerminal()) {
+    console.error('\n  Following scan log (Ctrl-C to stop watching):\n');
+  }
+  await tailUntilComplete(logFile);
+
+  const workflowId = resolveWorkflowId(workspace);
+  if (!workflowId) {
+    fail('Scan finished but its workflow id could not be resolved from session.json.');
+  }
+
+  try {
+    const outcome = await getTerminalOutcome(workflowId);
+    process.exit(outcome.kind === 'success' ? 0 : 1);
+  } catch {
+    fail('Could not reach Temporal at 127.0.0.1:7233 to read the scan outcome.');
+  }
+}
+
+function printPreservedContainerHint(containerName: string): void {
   console.log('');
   console.log(`  Worker container preserved: ${containerName}`);
   console.log(`    Inspect logs: docker logs ${containerName}`);
@@ -240,23 +276,19 @@ function printDebugHint(containerName: string): void {
   console.log('');
 }
 
-function printInfo(
-  args: StartArgs,
-  workspace: string,
-  workflowId: string,
-  repoPath: string,
-  workspacesDir: string,
-): void {
-  const logsCmd = isLocal() ? `./shannon logs ${workspace}` : `npx @keygraph/shannon logs ${workspace}`;
-  const reportPath = path.join(workspacesDir, workspace, FINAL_REPORT_FILENAME);
+function printInfo(args: StartArgs, workspace: string, repoPath: string, workspacesDir: string): void {
+  const interactive = stdoutIsTerminal();
+
+  if (interactive && !args.follow) {
+    console.log('  It runs in the background — you can close this terminal.');
+    console.log('');
+  }
 
-  console.log('  Scan started — it runs in the background, so you can close this terminal.');
-  console.log('');
   console.log(`  Target:     ${args.url}`);
-  console.log(`  Repository: ${repoPath}`);
+  console.log(`  Repository: ${interactive ? repoPath : path.basename(repoPath)}`);
   console.log(`  Workspace:  ${workspace}`);
   if (args.config) {
-    console.log(`  Config:     ${path.resolve(args.config)}`);
+    console.log(`  Config:     ${interactive ? path.resolve(args.config) : path.basename(args.config)}`);
   }
   if (args.pipelineTesting) {
     console.log('  Mode:       Pipeline Testing');
@@ -267,14 +299,22 @@ function printInfo(
     console.log(`  Model:      ${spec.providerId}:${spec.modelId}`);
   }
 
-  console.log('');
-  console.log('  Watch scan progress:');
-  console.log(`    Live logs:  ${logsCmd}`);
-  if (workflowId) {
-    console.log(`    Dashboard:  http://localhost:8233/namespaces/default/workflows/${workflowId}`);
-  } else {
-    console.log('    Dashboard:  http://localhost:8233');
+  if (!interactive) {
+    return;
   }
+
+  const reportPath = path.join(workspacesDir, workspace, FINAL_REPORT_PDF_FILENAME);
+
+  // When following, the scan log streams inline next, so the "run these to watch it" hints
+  // would only contradict that.
+  if (!args.follow) {
+    const prefix = commandPrefix();
+    console.log('');
+    console.log('  Watch scan progress:');
+    console.log(`    Live logs:  ${prefix} logs ${workspace}`);
+    console.log(`    Progress:   ${prefix} status ${workspace}`);
+  }
+
   console.log('');
   console.log('  Report (when the scan finishes):');
   console.log(`    ${reportPath}`);

apps/cli/src/commands/status.ts

@@ -1,24 +1,196 @@
 /**
- * `shannon status` command — show running scans and Temporal health.
+ * `shannon status <workspace>` — one scan's live progress from Temporal.
+ *
+ * While the scan runs, polls Temporal and redraws the phase/agent tree on a
+ * terminal (a pipe or a finished scan gets a single frame). When the scan reaches
+ * a terminal state, prints the overall result and exits. Reads Temporal directly —
+ * no worker, no session files — so it needs Temporal up and shows scans within its
+ * ~24h retention window.
  */
 
-import { isTemporalReady, listRunningWorkers } from '../docker.js';
+import { setTimeout as sleep } from 'node:timers/promises';
+import { fail } from '../errors.js';
+import { isLocal } from '../mode.js';
+import { type RenderInput, renderScan } from '../scan/render.js';
+import { toStatusJson } from '../scan/status-json.js';
+import { resolveWorkflowId } from '../session.js';
+import { displaySplash } from '../splash.js';
+import { describeScan, getTerminalOutcome, queryProgress, type ScanDescription } from '../temporal-client.js';
+import { stdoutIsTerminal, supportsColor } from '../tty.js';
+import { getVersion } from '../version.js';
 
-export function status(): void {
-  // 1. Temporal health
-  const temporalUp = isTemporalReady();
-  console.log(`Temporal: ${temporalUp ? 'running' : 'not running'}`);
-  if (temporalUp) {
-    console.log('  Dashboard: http://localhost:8233');
+const HIDE_CURSOR = '\x1b[?25l';
+const SHOW_CURSOR = '\x1b[?25h';
+/** Redraw cadence for the spinner animation; data is refreshed on the slower poll. */
+const RENDER_MS = 120;
+const POLL_MS = 1200;
+
+/** Terminal = anything other than an open, running execution. */
+function isTerminalStatus(status: string): boolean {
+  return status !== 'RUNNING' && status !== 'UNSPECIFIED';
+}
+
+// Match SGR color escapes (ESC[…m) so a line's on-screen width excludes them. Built from the ESC
+// char code so the source carries no literal control character.
+const ANSI_PATTERN = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, 'g');
+
+/**
+ * Physical terminal rows a frame occupies, so the live redraw moves the cursor up by the right
+ * amount. A line wider than the terminal wraps onto extra rows, so counting logical lines alone
+ * undercounts and the redraw drifts downward. Color escapes don't take screen columns, so strip them.
+ */
+function physicalRows(frame: string): number {
+  const columns = process.stdout.columns || 80;
+  return frame.split('\n').reduce((rows, line) => {
+    const width = line.replace(ANSI_PATTERN, '').length;
+    return rows + Math.max(1, Math.ceil(width / columns));
+  }, 0);
+}
+
+function exitCodeFor(input: RenderInput): number {
+  if (input.temporalStatus === 'FAILED' || input.temporalStatus === 'TIMED_OUT') return 1;
+  if (input.state?.status === 'failed') return 1;
+  return 0;
+}
+
+/** Live view of a running scan: its progress query plus the in-flight agents from describe. */
+async function buildRunningInput(workspace: string, workflowId: string, desc: ScanDescription): Promise<RenderInput> {
+  const state = await queryProgress(workflowId);
+  return {
+    workspace,
+    workflowId,
+    temporalStatus: desc.status,
+    state,
+    running: desc.runningAgents,
+    ...(desc.startedAt !== undefined && { startedAt: desc.startedAt }),
+  };
+}
+
+/** Final view of a closed scan: its result (or the failure) plus timing from describe. */
+async function buildTerminalInput(workspace: string, workflowId: string, desc: ScanDescription): Promise<RenderInput> {
+  const outcome = await getTerminalOutcome(workflowId);
+  const timing = {
+    ...(desc.startedAt !== undefined && { startedAt: desc.startedAt }),
+    ...(desc.closedAt !== undefined && { endedAt: desc.closedAt }),
+  };
+  if (outcome.kind === 'success') {
+    return { workspace, workflowId, temporalStatus: desc.status, state: outcome.state, running: [], ...timing };
   }
-  console.log('');
+  return {
+    workspace,
+    workflowId,
+    temporalStatus: desc.status,
+    state: null,
+    running: [],
+    failureMessage: outcome.message,
+    ...timing,
+  };
+}
 
-  // 2. Running scans
-  const workers = listRunningWorkers();
-  if (workers) {
-    console.log('Running scans:');
-    console.log(workers);
-  } else {
-    console.log('No scans running');
+function printFrame(input: RenderInput): void {
+  const frame = renderScan(input, {
+    now: Date.now(),
+    color: supportsColor(),
+    unicode: stdoutIsTerminal(),
+    live: false,
+    frame: 0,
+  });
+  process.stdout.write(`${frame}\n`);
+}
+
+/**
+ * Poll Temporal and redraw until the scan reaches a terminal state, then print the
+ * final frame and exit. A fast ticker animates the running spinner off the cached
+ * snapshot; the network poll refreshes that snapshot on a slower cadence.
+ */
+async function watch(workspace: string, workflowId: string): Promise<never> {
+  let prevRows = 0;
+  let frame = 0;
+  let cached: RenderInput | null = null;
+
+  const draw = (input: RenderInput, live: boolean): void => {
+    const out = renderScan(input, { now: Date.now(), color: supportsColor(), unicode: true, live, frame });
+    if (prevRows > 0) process.stdout.write(`\x1b[${prevRows}A\x1b[0J`);
+    process.stdout.write(`${out}\n`);
+    prevRows = physicalRows(out);
+  };
+
+  process.on('exit', () => process.stdout.write(SHOW_CURSOR));
+  process.on('SIGINT', () => {
+    process.stdout.write('\n');
+    process.exit(0);
+  });
+  process.stdout.write(HIDE_CURSOR);
+
+  const ticker = setInterval(() => {
+    frame++;
+    if (cached) draw(cached, true);
+  }, RENDER_MS);
+
+  for (;;) {
+    const desc = await describeScan(workflowId);
+    if (!desc) {
+      clearInterval(ticker);
+      fail(`Scan "${workspace}" is no longer in Temporal.`);
+    }
+
+    if (isTerminalStatus(desc.status)) {
+      clearInterval(ticker);
+      const input = await buildTerminalInput(workspace, workflowId, desc);
+      draw(input, false);
+      process.exit(exitCodeFor(input));
+    }
+
+    cached = await buildRunningInput(workspace, workflowId, desc);
+    await sleep(POLL_MS);
   }
 }
+
+/** Read one point-in-time snapshot from Temporal: the terminal result if closed, else live progress. */
+async function snapshot(workspace: string, workflowId: string, desc: ScanDescription): Promise<RenderInput> {
+  return isTerminalStatus(desc.status)
+    ? buildTerminalInput(workspace, workflowId, desc)
+    : buildRunningInput(workspace, workflowId, desc);
+}
+
+export async function status(workspace: string, opts: { readonly json: boolean }): Promise<void> {
+  // A resume spawns a new workflow id (recorded in session.json); resolve through there so status
+  // follows the current resume, not the superseded original. Fresh scans: the name is the id.
+  const workflowId = resolveWorkflowId(workspace) ?? workspace;
+
+  let desc: ScanDescription | null;
+  try {
+    desc = await describeScan(workflowId);
+  } catch {
+    fail('Could not reach Temporal at 127.0.0.1:7233.', 'Start Temporal (it comes up with a scan) and try again.');
+  }
+
+  if (!desc) {
+    fail(
+      `No scan found for "${workspace}".`,
+      '',
+      'Scans are visible while running and for ~24h after they finish (Temporal retention).',
+    );
+  }
+
+  // --json is always a single snapshot then exit, even on a TTY — it never enters the live watch loop.
+  if (opts.json) {
+    const input = await snapshot(workspace, workflowId, desc);
+    process.stdout.write(`${JSON.stringify(toStatusJson(input, Date.now()), null, 2)}\n`);
+    process.exit(exitCodeFor(input));
+  }
+
+  // Human-facing views open with the splash; skip it off a real terminal so piped output stays clean.
+  if (stdoutIsTerminal()) {
+    displaySplash(isLocal() ? undefined : getVersion());
+  }
+
+  // A finished scan, or output that isn't a live terminal, gets a single frame.
+  if (isTerminalStatus(desc.status) || !stdoutIsTerminal()) {
+    const input = await snapshot(workspace, workflowId, desc);
+    printFrame(input);
+    process.exit(exitCodeFor(input));
+  }
+
+  await watch(workspace, workflowId);
+}

apps/cli/src/commands/stop.ts

@@ -1,23 +1,127 @@
 /**
- * `shannon stop` command — stop workers and infrastructure.
+ * `shannon stop` command — stop one scan by workspace, or every scan with --all.
+ * Never touches infra or data; to wipe Temporal state entirely, use `shannon reset`.
  */
 
 import * as p from '@clack/prompts';
-import { stopInfra, stopWorkers } from '../docker.js';
-import { requireInteractive } from '../tty.js';
+import { confirmOrExit } from '../confirm.js';
+import {
+  anyRunningScanWorkflow,
+  ensureDocker,
+  isTemporalReady,
+  isWorkflowRunning,
+  runningContainers,
+  scanFilter,
+  stopContainers,
+  terminateAllWorkflows,
+  terminateWorkflow,
+  WORKER_FILTER,
+} from '../docker.js';
+import { fail, failUsage, warn } from '../errors.js';
+import { commandPrefix } from '../mode.js';
+import { resolveWorkflowId } from '../session.js';
 
-export async function stop(clean: boolean, yes: boolean): Promise<void> {
-  if (clean && !yes) {
-    requireInteractive('stop --clean', 'Re-run with --yes to skip this confirmation.');
-    const confirmed = await p.confirm({
-      message: 'This will stop all running scans and remove the Temporal data. Continue?',
-    });
-    if (p.isCancel(confirmed) || !confirmed) {
-      p.cancel('Aborted.');
-      process.exit(0);
+export interface StopOptions {
+  all: boolean;
+  yes: boolean;
+  workspace?: string;
+}
+
+/**
+ * Stop a single scan. Terminating the workflow both clears Temporal's record and
+ * brings the container down (the worker waits on the workflow result), so that runs
+ * first; `docker stop` is the fallback for the pre-registration window and an
+ * unreachable Temporal. The stop is then verified rather than assumed.
+ */
+async function stopSingleScan(workspace: string, yes: boolean): Promise<void> {
+  const workflowId = resolveWorkflowId(workspace);
+  const filter = scanFilter(workspace);
+  const temporalUp = isTemporalReady();
+
+  const initialContainers = runningContainers(filter);
+  const workflowRunning = Boolean(workflowId && temporalUp && isWorkflowRunning(workflowId));
+
+  // Resolve what is running before prompting, so we never confirm a no-op.
+  if (initialContainers.length === 0 && !workflowRunning) {
+    if (!workflowId) {
+      fail(`No scan found for workspace: ${workspace}`);
     }
+    console.log(`Nothing was running for ${workspace}.`);
+    return;
   }
 
-  stopWorkers();
-  stopInfra(clean);
+  await confirmOrExit('stop', `Stop the scan "${workspace}"?`, yes);
+
+  const spinner = p.spinner();
+  spinner.start(`Stopping scan ${workspace}`);
+
+  if (workflowId && workflowRunning) {
+    terminateWorkflow(workflowId, `Stopped via shannon stop ${workspace}`);
+  }
+  await stopContainers(runningContainers(filter));
+
+  const stillRunning = runningContainers(filter);
+  if (stillRunning.length > 0) {
+    spinner.error(`Scan ${workspace} may still be running`);
+    console.error(`${stillRunning.length} container(s) did not stop. Retry: ${commandPrefix()} stop ${workspace}`);
+    process.exit(1);
+  }
+
+  spinner.stop(`Stopped scan ${workspace}`);
+
+  if (workflowId && temporalUp && isWorkflowRunning(workflowId)) {
+    warn(`scan ${workspace} stopped, but its workflow is still Running in Temporal.`);
+  }
+}
+
+async function stopAllScans(yes: boolean): Promise<void> {
+  const temporalUp = isTemporalReady();
+  const initial = runningContainers(WORKER_FILTER);
+
+  // Resolve what is running before prompting, so we never confirm a no-op.
+  if (initial.length === 0) {
+    console.log('No running scans to stop.');
+    return;
+  }
+
+  await confirmOrExit('stop', 'This will stop all running scans. Continue?', yes);
+
+  const spinner = p.spinner();
+  spinner.start('Stopping all scans');
+
+  if (temporalUp) {
+    terminateAllWorkflows('Stopped via shannon stop --all');
+  }
+  await stopContainers(runningContainers(WORKER_FILTER));
+
+  const stillRunning = runningContainers(WORKER_FILTER);
+  if (stillRunning.length > 0) {
+    spinner.error(`Stopped ${initial.length - stillRunning.length} of ${initial.length} scans`);
+    console.error(`${stillRunning.length} container(s) did not stop. Retry: ${commandPrefix()} stop --all`);
+    process.exit(1);
+  }
+
+  spinner.stop(`Stopped ${initial.length} scan${initial.length === 1 ? '' : 's'}`);
+
+  if (temporalUp && anyRunningScanWorkflow()) {
+    warn('some scan workflows are still Running in Temporal — check http://localhost:8233');
+  }
+}
+
+export async function stop(opts: StopOptions): Promise<void> {
+  ensureDocker();
+
+  // Validate the target: exactly one of <workspace> or --all.
+  if (opts.all && opts.workspace) {
+    failUsage('Pass a workspace name or --all, not both.');
+  }
+  if (!opts.all && !opts.workspace) {
+    failUsage('Specify which scan to stop: `stop <workspace>`, or `stop --all` to stop every scan.');
+  }
+
+  if (opts.workspace) {
+    await stopSingleScan(opts.workspace, opts.yes);
+  } else {
+    await stopAllScans(opts.yes);
+  }
 }

apps/cli/src/commands/uninstall.ts

@@ -1,55 +0,0 @@
-/**
- * `npx @keygraph/shannon uninstall` command — remove ~/.shannon/ after confirmation (npx only).
- */
-
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import * as p from '@clack/prompts';
-import { stopInfra, stopWorkers } from '../docker.js';
-import { requireInteractive } from '../tty.js';
-
-const SHANNON_HOME = path.join(os.homedir(), '.shannon');
-
-export async function uninstall(yes: boolean): Promise<void> {
-  const interactive = !yes;
-  if (interactive) p.intro('Shannon Uninstall');
-
-  if (!fs.existsSync(SHANNON_HOME)) {
-    const message = 'Nothing to remove. Shannon is not configured on this machine.';
-    if (interactive) {
-      p.log.info(message);
-      p.outro('Done.');
-    } else {
-      console.log(message);
-    }
-    return;
-  }
-
-  if (interactive) {
-    requireInteractive('uninstall', 'Re-run with --yes to skip this confirmation.');
-    const confirmed = await p.confirm({
-      message: 'This will permanently remove all past scan data, saved configurations, and API keys. Continue?',
-    });
-    if (p.isCancel(confirmed) || !confirmed) {
-      p.cancel('Aborted.');
-      process.exit(0);
-    }
-  }
-
-  // Stop any running containers first
-  stopWorkers();
-  stopInfra(false);
-
-  fs.rmSync(SHANNON_HOME, { recursive: true, force: true });
-
-  const done = 'All Shannon data has been removed.';
-  const hint = 'Shannon has been uninstalled. Run `npx @keygraph/shannon setup` to start fresh.';
-  if (interactive) {
-    p.log.success(done);
-    p.outro(hint);
-  } else {
-    console.log(done);
-    console.log(hint);
-  }
-}

apps/cli/src/commands/workspaces.ts

@@ -1,35 +0,0 @@
-/**
- * `shannon workspaces` command — list all workspaces.
- */
-
-import { execFileSync } from 'node:child_process';
-import os from 'node:os';
-import { getWorkerImage } from '../docker.js';
-import { getWorkspacesDir } from '../home.js';
-
-export function workspaces(version: string): void {
-  const workspacesDir = getWorkspacesDir();
-  const image = getWorkerImage(version);
-
-  try {
-    execFileSync(
-      'docker',
-      [
-        'run',
-        '--rm',
-        '-v',
-        `${workspacesDir}:/app/workspaces`,
-        '-e',
-        'WORKSPACES_DIR=/app/workspaces',
-        image,
-        'node',
-        'apps/worker/dist/temporal/workspaces.js',
-      ],
-      { stdio: 'inherit', ...(os.platform() === 'win32' && { env: { ...process.env, MSYS_NO_PATHCONV: '1' } }) },
-    );
-  } catch {
-    console.error('ERROR: Failed to list workspaces. Is the Docker image available?');
-    console.error(`  Run: docker pull ${image}`);
-    process.exit(1);
-  }
-}

apps/cli/src/config/resolver.ts

@@ -7,9 +7,16 @@
 
 import fs from 'node:fs';
 import { parse as parseTOML } from 'smol-toml';
+import { fail } from '../errors.js';
 import { getConfigFile } from '../home.js';
 import { getMode } from '../mode.js';
-import { DEFAULT_MODEL_SPEC, type ProviderId, parseModelSpec } from '../model-spec.js';
+import {
+  type CuratedProviderId,
+  DEFAULT_MODEL_SPEC,
+  GENERIC_API_KEY_ENV,
+  isCuratedProvider,
+  parseModelSpec,
+} from '../model-spec.js';
 
 // === TOML ↔ Env Mapping ===
 
@@ -42,16 +49,22 @@ const CONFIG_MAP: readonly ConfigMapping[] = [
   // Bedrock
   { env: 'AWS_REGION', toml: 'bedrock.region', type: 'string' },
   { env: 'AWS_BEARER_TOKEN_BEDROCK', toml: 'bedrock.token', type: 'string' },
+
+  // Generic — credential for any provider Shannon does not curate
+  { env: GENERIC_API_KEY_ENV, toml: 'provider.api_key', type: 'string' },
 ] as const;
 
-/** TOML section holding each provider's credentials, keyed by provider id. */
-const PROVIDER_SECTIONS: Readonly<Record<ProviderId, string>> = {
+/** TOML section holding each curated provider's credentials, keyed by provider id. */
+const PROVIDER_SECTIONS: Readonly<Record<CuratedProviderId, string>> = {
   anthropic: 'anthropic',
   openai: 'openai',
   xai: 'xai',
   'amazon-bedrock': 'bedrock',
 };
 
+/** TOML section holding the generic credential for uncurated providers. */
+const GENERIC_PROVIDER_SECTION = 'provider';
+
 // === TOML Parsing ===
 
 type TOMLValue = string | number | boolean;
@@ -88,10 +101,9 @@ function loadTOML(): TOMLConfig | null {
     const mode = fs.statSync(configPath).mode;
     if (mode & 0o077) {
       const actual = (mode & 0o777).toString(8).padStart(3, '0');
-      console.error(
-        `\nYour config file is readable by other users on this machine (${actual}). Lock it down: chmod 600 ${configPath}\n`,
+      fail(
+        `Your config file is readable by other users on this machine (${actual}). Lock it down: chmod 600 ${configPath}`,
       );
-      process.exit(1);
     }
   }
 
@@ -100,9 +112,7 @@ function loadTOML(): TOMLConfig | null {
     return parseTOML(content) as TOMLConfig;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`\nFailed to parse ${configPath}: ${message}`);
-    console.error(`\nRun 'npx @keygraph/shannon setup' to reconfigure.\n`);
-    process.exit(1);
+    fail(`Failed to parse ${configPath}: ${message}`, `Run 'npx @keygraph/shannon setup' to reconfigure.`);
   }
 }
 
@@ -128,9 +138,18 @@ function buildSchema(): Map<string, Map<string, TOMLType>> {
 /**
  * Check that the section backing the selected provider carries a usable
  * credential. `core.model` names the provider, so only that section is required;
- * other providers' sections are ignored and never forwarded.
+ * other providers' sections are ignored and never forwarded. An uncurated
+ * provider draws its credential from the generic [provider] section.
  */
-function validateProviderFields(config: TOMLConfig, providerId: ProviderId, errors: string[]): void {
+function validateProviderFields(config: TOMLConfig, providerId: string, errors: string[]): void {
+  if (!isCuratedProvider(providerId)) {
+    const section = config[GENERIC_PROVIDER_SECTION] as Record<string, unknown> | undefined;
+    if (!section || !Object.keys(section).includes('api_key')) {
+      errors.push(`[${GENERIC_PROVIDER_SECTION}] requires api_key for provider "${providerId}"`);
+    }
+    return;
+  }
+
   const sectionName = PROVIDER_SECTIONS[providerId];
   const section = config[sectionName] as Record<string, unknown> | undefined;
   const keys = section ? Object.keys(section) : [];
@@ -235,12 +254,11 @@ export function resolveConfig(): void {
   // Validate before injecting
   const errors = validateConfig(toml);
   if (errors.length > 0) {
-    console.error('\nInvalid configuration:');
-    for (const err of errors) {
-      console.error(`  - ${err}`);
-    }
-    console.error(`\nRun 'npx @keygraph/shannon setup' to reconfigure.\n`);
-    process.exit(1);
+    fail(
+      'Invalid configuration:',
+      ...errors.map((err) => `  - ${err}`),
+      `Run 'npx @keygraph/shannon setup' to reconfigure.`,
+    );
   }
 
   for (const mapping of CONFIG_MAP) {

apps/cli/src/config/writer.ts

@@ -13,6 +13,8 @@ export interface ShannonConfig {
   openai?: { api_key?: string; format?: string };
   xai?: { api_key?: string };
   bedrock?: { region?: string; token?: string };
+  /** Generic credential for any provider Shannon does not curate. Maps to SHANNON_AI_API_KEY. */
+  provider?: { api_key?: string };
 }
 
 // === File Operations ===

apps/cli/src/confirm.ts

@@ -0,0 +1,43 @@
+/**
+ * Shared confirmation prompt for destructive or batch commands.
+ *
+ * `stop` and `reset` gate their action behind the same "confirm unless --yes"
+ * flow. Centralizing it here keeps the behavior identical across commands and
+ * impossible to change in only one place by accident.
+ */
+
+import * as p from '@clack/prompts';
+import { requireInteractive } from './tty.js';
+
+/**
+ * Ask the user to confirm an action, unless `yes` was passed. Off a TTY without
+ * `--yes`, fails fast rather than hanging on a prompt. Exits 0 if the user declines.
+ */
+export async function confirmOrExit(command: string, message: string, yes: boolean): Promise<void> {
+  if (yes) {
+    return;
+  }
+
+  requireInteractive(command, 'Re-run with --yes to skip this confirmation.');
+  const confirmed = await p.confirm({ message });
+  if (p.isCancel(confirmed) || !confirmed) {
+    p.cancel('Aborted.');
+    process.exit(0);
+  }
+}
+
+/**
+ * Severe-tier confirmation: the user must type `word` exactly to proceed. Unlike
+ * `confirmOrExit` there is no `--yes` bypass. Off a TTY it fails fast; exits 0 if declined.
+ */
+export async function confirmByTyping(command: string, word: string): Promise<void> {
+  requireInteractive(command, `'${command}' cannot be run non-interactively.`);
+  const typed = await p.text({
+    message: `Type ${word} to confirm — this cannot be undone:`,
+    validate: (value) => (value === word ? undefined : `Type ${word} to proceed, or press Ctrl-C to abort.`),
+  });
+  if (p.isCancel(typed) || typed !== word) {
+    p.cancel('Aborted.');
+    process.exit(0);
+  }
+}

apps/cli/src/docker.ts

@@ -12,14 +12,21 @@ import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
+import type { SpinnerResult } from '@clack/prompts';
+import { envBool, PI_AUTH_CONTAINER_PATH } from './env.js';
+import { fail } from './errors.js';
 import { getMode, isDevMode } from './mode.js';
 import { INTERNAL_DIR } from './paths.js';
+import { runStep, spawnCaptured, surfaceOutput } from './ui.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 const NPX_IMAGE_REPO = 'keygraph/shannon';
 const DEV_IMAGE = 'shannon-worker';
 
+/** Docker label stamped on each worker container, mapping it back to its workspace so a single scan can be stopped by name. */
+const WORKSPACE_LABEL = 'shannon.workspace';
+
 export function getWorkerImage(version: string): string {
   return getMode() === 'local' ? DEV_IMAGE : `${NPX_IMAGE_REPO}:${version}`;
 }
@@ -65,44 +72,77 @@ function runOutput(cmd: string, args: string[]): string {
   }
 }
 
+/** Run a command asynchronously, resolving true on success. Never rejects. */
+function spawnQuiet(cmd: string, args: string[]): Promise<boolean> {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'ignore' });
+    child.on('close', (code) => resolve(code === 0));
+    child.on('error', () => resolve(false));
+  });
+}
+
+const TEMPORAL_CONTAINER = 'shannon-temporal';
+const TEMPORAL_ADDRESS = 'localhost:7233';
+
+/** Query matching every running pentest scan workflow. */
+const RUNNING_SCAN_QUERY = "ExecutionStatus = 'Running' AND WorkflowType = 'pentestPipelineWorkflow'";
+
+/** Build `docker exec` args for a `temporal` CLI command run inside the Temporal container. */
+function temporalCmd(...args: string[]): string[] {
+  return ['exec', TEMPORAL_CONTAINER, 'temporal', ...args, '--address', TEMPORAL_ADDRESS];
+}
+
+/**
+ * Verify Docker is installed and its daemon is running, exiting otherwise.
+ * `docker info` succeeds only when both are true. Call this before any command
+ * that shells out to Docker.
+ */
+export function ensureDocker(): void {
+  try {
+    execFileSync('docker', ['info'], { stdio: 'pipe' });
+  } catch {
+    fail(
+      'Docker must be installed and running. Start Docker and try again.',
+      'Install Docker: https://docs.docker.com/get-docker/',
+    );
+  }
+}
+
 /**
  * Check if Temporal is running and healthy.
  */
 export function isTemporalReady(): boolean {
-  const output = runOutput('docker', [
-    'exec',
-    'shannon-temporal',
-    'temporal',
-    'operator',
-    'cluster',
-    'health',
-    '--address',
-    'localhost:7233',
-  ]);
+  const output = runOutput('docker', temporalCmd('operator', 'cluster', 'health'));
   return output.includes('SERVING');
 }
 
 /**
  * Ensure Temporal is running via compose.
  */
-export async function ensureInfra(): Promise<void> {
+export async function ensureInfra(spinner: SpinnerResult): Promise<void> {
   if (isTemporalReady()) {
     return;
   }
 
+  // Drive the caller's spinner — the whole "start" flow is one spinner, not several.
+  spinner.message('Starting Temporal');
   const composeFile = getComposeFile();
-  console.log('Starting Shannon infrastructure...');
-  execFileSync('docker', ['compose', '-f', composeFile, 'up', '-d'], { stdio: 'inherit' });
+  const result = await spawnCaptured('docker', ['compose', '-f', composeFile, 'up', '-d']);
+  if (!result.ok) {
+    spinner.error('Could not start Temporal');
+    surfaceOutput(result.output);
+    process.exit(1);
+  }
 
-  console.log('Waiting for Temporal to be ready...');
+  spinner.message('Waiting for Temporal to be ready');
   for (let i = 0; i < 30; i++) {
     if (isTemporalReady()) {
-      console.log('Temporal is ready!');
       return;
     }
     await sleep(2000);
   }
-  console.error('Timeout waiting for Temporal');
+
+  spinner.error('Temporal did not become ready in time');
   process.exit(1);
 }
 
@@ -137,10 +177,11 @@ export function ensureImage(version: string): void {
     try {
       execFileSync('docker', ['pull', image], { stdio: 'inherit' });
     } catch {
-      console.error(`\nERROR: Failed to pull ${image}`);
-      console.error('The image may not be available for your platform yet.');
-      console.error('Check https://hub.docker.com/r/keygraph/shannon for available tags.');
-      process.exit(1);
+      fail(
+        `Failed to pull ${image}`,
+        'The image may not be available for your platform yet.',
+        'Check https://hub.docker.com/r/keygraph/shannon for available tags.',
+      );
     }
     pruneOldImages(version);
   }
@@ -203,7 +244,7 @@ function shouldSkipHostsName(name: string, hostname: string): boolean {
  * `host-gateway` so they target the host's loopback instead of the container's.
  */
 function forwardEtcHostsFlags(): string[] {
-  if (process.env.SHANNON_FORWARD_HOSTS === 'false') return [];
+  if (!envBool('SHANNON_FORWARD_HOSTS', true)) return [];
   if (os.platform() === 'win32') return [];
 
   let content: string;
@@ -254,20 +295,24 @@ export interface WorkerOptions {
   outputDir?: string;
   workspace: string;
   pipelineTesting?: boolean;
-  debug?: boolean;
+  keepContainer?: boolean;
+  piAuthHostPath?: string;
 }
 
 /**
  * Spawn the worker container in detached mode and return the process.
- * When `opts.debug` is true, omits `--rm` so the container persists for log inspection.
+ * When `opts.keepContainer` is true, omits `--rm` so the container persists for log inspection.
  */
 export function spawnWorker(opts: WorkerOptions): ChildProcess {
   const args = ['run', '-d'];
-  if (!opts.debug) {
+  if (!opts.keepContainer) {
     args.push('--rm');
   }
   args.push('--name', opts.containerName, '--network', 'shannon-net');
 
+  // Tag with the workspace so `stop <workspace>` can target this scan's container
+  args.push('--label', `${WORKSPACE_LABEL}=${opts.workspace}`);
+
   // Add host flag for Linux
   args.push(...addHostFlag());
 
@@ -305,6 +350,11 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
     args.push('-v', `${opts.outputDir}:/app/output`);
   }
 
+  // Reuse the host's pi credentials: mount only the auth file, allowing token refreshes to persist.
+  if (opts.piAuthHostPath) {
+    args.push('-v', `${opts.piAuthHostPath}:${PI_AUTH_CONTAINER_PATH}`);
+  }
+
   // Environment
   args.push(...opts.envFlags);
 
@@ -337,26 +387,86 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
   });
 }
 
-/**
- * Stop all running shannon-worker-* containers.
- */
-export function stopWorkers(): void {
-  const workers = runOutput('docker', ['ps', '-q', '--filter', 'name=shannon-worker-']);
-  if (!workers) return;
+/** `docker ps --filter` args matching every running worker container. */
+export const WORKER_FILTER: readonly string[] = ['--filter', 'name=shannon-worker-'];
 
-  const ids = workers.split('\n').filter(Boolean);
-  console.log('Stopping running scans...');
-  execFileSync('docker', ['stop', ...ids], { stdio: 'inherit' });
+/** `docker ps --filter` args matching one scan's worker container(s), by workspace label. */
+export function scanFilter(workspace: string): readonly string[] {
+  return ['--filter', `label=${WORKSPACE_LABEL}=${workspace}`];
 }
 
 /**
- * Tear down the compose stack.
+ * IDs of running containers matching the filter. Re-querying this after a stop is
+ * the authoritative check for whether containers actually stopped — `docker stop`'s
+ * exit code can't distinguish "already gone" from "failed to stop".
  */
-export function stopInfra(clean: boolean): void {
+export function runningContainers(filter: readonly string[]): string[] {
+  const output = runOutput('docker', ['ps', '-q', ...filter]);
+  return output.split('\n').filter(Boolean);
+}
+
+/**
+ * Stop containers by ID, tolerating any that vanished between being listed and
+ * stopped (a `--rm` worker exiting is success, not an error). Async so a spinner
+ * can animate during docker's graceful-shutdown wait.
+ */
+export async function stopContainers(ids: string[]): Promise<void> {
+  await Promise.all(ids.map((id) => spawnQuiet('docker', ['stop', id])));
+}
+
+/**
+ * Terminate a Temporal workflow so a stopped scan doesn't linger as a running
+ * workflow with no worker. Best-effort: returns false if Temporal is unreachable
+ * or the workflow already closed. Requires Temporal to be up (guard with isTemporalReady).
+ */
+export function terminateWorkflow(workflowId: string, reason: string): boolean {
+  return runQuiet('docker', temporalCmd('workflow', 'terminate', '--workflow-id', workflowId, '--reason', reason));
+}
+
+/**
+ * Terminate every running pentest workflow in one batch, so `stop --all` doesn't
+ * leave workflows running with no worker. Best-effort: returns false if Temporal
+ * is unreachable. Requires Temporal to be up (guard with isTemporalReady).
+ */
+export function terminateAllWorkflows(reason: string): boolean {
+  return runQuiet(
+    'docker',
+    temporalCmd('workflow', 'terminate', '--query', RUNNING_SCAN_QUERY, '--reason', reason, '--yes'),
+  );
+}
+
+/**
+ * Whether a specific workflow is still in the Running state. Re-querying this after
+ * a terminate verifies it actually took effect, rather than trusting the terminate
+ * command's exit code. Requires Temporal to be up (guard with isTemporalReady).
+ */
+export function isWorkflowRunning(workflowId: string): boolean {
+  const query = `WorkflowId = '${workflowId}' AND ExecutionStatus = 'Running'`;
+  const output = runOutput('docker', temporalCmd('workflow', 'list', '--query', query));
+  return output.includes(workflowId);
+}
+
+/**
+ * Whether any pentest scan workflow is still Running — the `stop --all` counterpart
+ * to isWorkflowRunning. Requires Temporal to be up (guard with isTemporalReady).
+ */
+export function anyRunningScanWorkflow(): boolean {
+  const output = runOutput('docker', temporalCmd('workflow', 'list', '--query', RUNNING_SCAN_QUERY));
+  return output.includes('pentestPipelineWorkflow');
+}
+
+/**
+ * Tear down the compose stack. When `clean` is set, volumes are removed too.
+ */
+export async function stopInfra(clean: boolean): Promise<void> {
   const composeFile = getComposeFile();
   const args = ['compose', '-f', composeFile, 'down'];
   if (clean) args.push('-v');
-  execFileSync('docker', args, { stdio: 'inherit' });
+  const label = clean ? 'Removing Temporal data and volumes' : 'Stopping Temporal';
+  const step = await runStep(label, 'docker', args);
+  if (!step.ok) {
+    fail(`${label} failed. See the output above.`);
+  }
 }
 
 /**
@@ -372,16 +482,3 @@ function pruneOldImages(currentVersion: string): void {
     runQuiet('docker', ['rmi', `${NPX_IMAGE_REPO}:${tag}`]);
   }
 }
-
-/**
- * List running worker containers.
- */
-export function listRunningWorkers(): string {
-  return runOutput('docker', [
-    'ps',
-    '--filter',
-    'name=shannon-worker-',
-    '--format',
-    'table {{.Names}}\t{{.Status}}\t{{.RunningFor}}',
-  ]);
-}

apps/cli/src/env.ts

@@ -5,32 +5,73 @@
  * NPX mode: fills gaps from ~/.shannon/config.toml (no .env).
  */
 
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import dotenv from 'dotenv';
 import { resolveConfig } from './config/resolver.js';
 import { getMode } from './mode.js';
 import {
+  CURATED_PROVIDERS,
+  type CuratedProviderId,
+  GENERIC_API_KEY_ENV,
+  isCuratedProvider,
   PROVIDER_API_KEY_ENV,
   PROVIDER_CREDENTIAL_HINT,
   PROVIDER_EXTRA_ENV,
-  type ProviderId,
   resolveModelSpec,
-  SUPPORTED_PROVIDERS,
 } from './model-spec.js';
 
 /**
  * Variables forwarded to every worker container regardless of provider. Each is
  * forwarded only when set, so an unused one never appears in the container.
+ * SHANNON_AI_API_KEY rides along because it is provider-neutral.
  */
-const COMMON_FORWARD_VARS = ['SHANNON_AI_MODEL', 'SHANNON_AI_BASE_URL', 'SHANNON_AI_OPENAI_FORMAT'] as const;
+const COMMON_FORWARD_VARS = [
+  'SHANNON_AI_MODEL',
+  'SHANNON_AI_BASE_URL',
+  'SHANNON_AI_OPENAI_FORMAT',
+  GENERIC_API_KEY_ENV,
+] as const;
 
 /**
  * Credential variables for one provider. Only the selected provider's entries are
- * forwarded, so a key for an unused provider never enters the scan container.
+ * forwarded, so a key for an unused provider never enters the scan container. An
+ * uncurated provider has none — it relies on the common SHANNON_AI_API_KEY.
  */
-function providerForwardVars(providerId: ProviderId): readonly string[] {
+function providerForwardVars(providerId: string): readonly string[] {
+  if (!isCuratedProvider(providerId)) return [];
   return [...PROVIDER_API_KEY_ENV[providerId], ...PROVIDER_EXTRA_ENV[providerId]];
 }
 
+/** Parse a user-facing boolean env var: `1`/`true` (any case) true, `0`/`false`/empty false, else the default. */
+export function envBool(name: string, defaultValue: boolean): boolean {
+  const raw = process.env[name]?.trim().toLowerCase();
+  if (raw === undefined || raw === '') return defaultValue;
+  if (raw === '1' || raw === 'true') return true;
+  if (raw === '0' || raw === 'false') return false;
+  return defaultValue;
+}
+
+const USE_PI_AUTH_ENV = 'SHANNON_USE_PI_AUTH';
+
+/** Where the host's auth.json is mounted: pi's standard location (worker HOME is /tmp), read natively. */
+export const PI_AUTH_CONTAINER_PATH = '/tmp/.pi/agent/auth.json';
+
+/** Host path to pi's credential file. */
+export function resolveHostPiAuthPath(): string {
+  return path.join(os.homedir(), '.pi', 'agent', 'auth.json');
+}
+
+export function piAuthFlagEnabled(): boolean {
+  return envBool(USE_PI_AUTH_ENV, false);
+}
+
+/** Opted into pi auth via the flag, and the auth file exists to mount. */
+export function shouldUsePiAuth(): boolean {
+  return piAuthFlagEnabled() && fs.existsSync(resolveHostPiAuthPath());
+}
+
 /**
  * Load credentials into process.env.
  * Local mode: loads ./.env via dotenv.
@@ -46,8 +87,9 @@ export function loadEnv(): void {
 }
 
 /**
- * Build `-e KEY=VALUE` flags for docker run. Forwards the common vars plus only
- * the selected provider's credentials.
+ * Build `-e` flags for docker run. Forwards the common vars plus only the
+ * selected provider's credentials, passed by name (`-e KEY`) so secret values
+ * stay out of the `docker run` argv; docker inherits them from this process's env.
  */
 export function buildEnvFlags(): string[] {
   const flags: string[] = ['-e', 'TEMPORAL_ADDRESS=shannon-temporal:7233'];
@@ -56,9 +98,8 @@ export function buildEnvFlags(): string[] {
   const providerVars = typeof spec === 'string' ? [] : providerForwardVars(spec.providerId);
 
   for (const key of [...COMMON_FORWARD_VARS, ...providerVars]) {
-    const value = process.env[key];
-    if (value) {
-      flags.push('-e', `${key}=${value}`);
+    if (process.env[key]) {
+      flags.push('-e', key);
     }
   }
 
@@ -70,22 +111,23 @@ interface CredentialValidation {
   error?: string;
 }
 
-/**
- * Whether the selected provider has a usable credential in the environment. Any
- * one API key satisfies a key-based provider; Bedrock instead needs every one of
- * its AWS_ vars.
- */
-function hasCredential(providerId: ProviderId): boolean {
+/** Whether a curated provider has its own named credential set (API key plus any extra var). */
+function hasNamedCredential(providerId: CuratedProviderId): boolean {
   const apiKeys = PROVIDER_API_KEY_ENV[providerId];
-  if (apiKeys.length > 0 && !apiKeys.some((name) => Boolean(process.env[name]))) {
-    return false;
-  }
+  if (!apiKeys.some((name) => Boolean(process.env[name]))) return false;
   return PROVIDER_EXTRA_ENV[providerId].every((name) => Boolean(process.env[name]));
 }
 
-/** Every provider that currently has a complete credential in the environment. */
-function configuredProviders(): ProviderId[] {
-  return SUPPORTED_PROVIDERS.filter((providerId) => hasCredential(providerId));
+/** Whether the selected provider has a credential. Bedrock needs its AWS_ vars; the generic key never stands in for it. */
+function hasCredential(providerId: string): boolean {
+  if (providerId === 'amazon-bedrock') return hasNamedCredential('amazon-bedrock');
+  if (isCuratedProvider(providerId) && hasNamedCredential(providerId)) return true;
+  return Boolean(process.env[GENERIC_API_KEY_ENV]);
+}
+
+/** Curated providers with a named credential. The generic key is neutral, so it never counts toward ambiguity. */
+function configuredProviders(): CuratedProviderId[] {
+  return CURATED_PROVIDERS.filter((providerId) => hasNamedCredential(providerId));
 }
 
 /**
@@ -93,17 +135,32 @@ function configuredProviders(): ProviderId[] {
  * Runs before any Docker work so mistakes fail immediately.
  */
 export function validateCredentials(): CredentialValidation {
-  // 1. Model selection must parse and name a supported provider
+  // 1. Model selection must parse into a provider and model id
   const spec = resolveModelSpec();
   if (typeof spec === 'string') {
     return { valid: false, error: spec };
   }
 
+  // Pi-auth: skip the API-key checks, but the host auth file must exist to mount.
+  if (piAuthFlagEnabled()) {
+    const authPath = resolveHostPiAuthPath();
+    if (!fs.existsSync(authPath)) {
+      return {
+        valid: false,
+        error: `${USE_PI_AUTH_ENV} is set but no pi credentials were found at ${authPath}. Authenticate with pi first.`,
+      };
+    }
+    return { valid: true };
+  }
+
   // 2. The selected provider must have a credential
   if (!hasCredential(spec.providerId)) {
+    const requirement = isCuratedProvider(spec.providerId)
+      ? PROVIDER_CREDENTIAL_HINT[spec.providerId]
+      : GENERIC_API_KEY_ENV;
     const hint =
       getMode() === 'local'
-        ? `Set ${PROVIDER_CREDENTIAL_HINT[spec.providerId]} in .env or export it.`
+        ? `Set ${requirement} in .env or export it.`
         : `Export the variables or run 'npx @keygraph/shannon setup'.`;
     return {
       valid: false,
@@ -114,8 +171,28 @@ export function validateCredentials(): CredentialValidation {
   // 3. Exactly one provider may be configured. Several complete credentials make
   //    the scan's provider depend on SHANNON_AI_MODEL alone, which is too easy to
   //    misread as "both are in play" and too easy to redirect by editing one line.
-  if (configuredProviders().length > 1) {
-    return { valid: false, error: 'Credentials for more than one provider are set.' };
+  const configured = configuredProviders();
+  if (configured.length > 1) {
+    const setKeys = (id: CuratedProviderId): string[] =>
+      PROVIDER_API_KEY_ENV[id].filter((name) => Boolean(process.env[name]));
+    const list = configured.map((id) => `${id} (${setKeys(id).join(', ')})`).join(' and ');
+    const others = configured.filter((id) => id !== spec.providerId);
+    const extraVars = others.flatMap(setKeys);
+
+    const dropHint =
+      getMode() === 'local'
+        ? 'remove them from .env or unset them in your shell:'
+        : "unset them in your shell, or reconfigure with 'npx @keygraph/shannon setup':";
+
+    const lines = [`Credentials for more than one provider are set: ${list}.`];
+    if (extraVars.length > 0) {
+      lines.push(
+        `Shannon runs one provider per scan, selected by SHANNON_AI_MODEL ("${spec.providerId}:...").`,
+        `Keep ${spec.providerId} and drop the rest — ${dropHint}`,
+        `  unset ${extraVars.join(' ')}`,
+      );
+    }
+    return { valid: false, error: lines.join('\n') };
   }
 
   return { valid: true };

apps/cli/src/errors.ts

@@ -0,0 +1,70 @@
+/**
+ * Centralized error reporting.
+ *
+ * `fail` — an expected, user-fixable error (bad input, missing prerequisite):
+ * a clean message on stderr and a non-zero exit, never a stack trace.
+ * `failUsage` — a malformed invocation (unknown command, bad or missing
+ * arguments): the same clean message, but a distinct exit code so callers can
+ * tell a usage mistake from an operational failure.
+ * `crash` — an unexpected error (a bug): a brief message, the full stack written
+ * to a log file for a bug report, and a pointer to the issue tracker.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const ISSUES_URL = 'https://github.com/KeygraphHQ/shannon/issues';
+
+/** Report an expected, user-fixable error (with optional extra lines) and exit non-zero. */
+export function fail(message: string, ...hints: string[]): never {
+  console.error(`ERROR: ${message}`);
+  for (const hint of hints) {
+    console.error(hint);
+  }
+  process.exit(1);
+}
+
+/** Report a usage/argument error (with optional extra lines) and exit 2. */
+export function failUsage(message: string, ...hints: string[]): never {
+  console.error(`ERROR: ${message}`);
+  for (const hint of hints) {
+    console.error(hint);
+  }
+  process.exit(2);
+}
+
+/** Report a non-fatal warning on stderr (with optional extra lines) without exiting. */
+export function warn(message: string, ...hints: string[]): void {
+  console.error(`WARNING: ${message}`);
+  for (const hint of hints) {
+    console.error(hint);
+  }
+}
+
+/** Report an unexpected error: brief message, full stack to a log file, plus the issue link. */
+export function crash(error: unknown): never {
+  console.error(`ERROR: ${error instanceof Error ? error.message : String(error)}`);
+  if (process.env.DEBUG) {
+    console.error(error instanceof Error ? error.stack : String(error));
+  }
+
+  const logPath = writeCrashLog(error);
+  if (logPath) {
+    console.error(`Details written to ${logPath}`);
+  }
+  console.error(`If this looks like a bug, please report it: ${ISSUES_URL}`);
+  process.exit(1);
+}
+
+/** Write the full error and stack to a log file; return its path, or null if it can't be written. */
+function writeCrashLog(error: unknown): string | null {
+  try {
+    const logPath = path.join(os.tmpdir(), 'shannon-error.log');
+    const detail = error instanceof Error && error.stack ? error.stack : String(error);
+    fs.writeFileSync(logPath, `${new Date().toISOString()}\n${detail}\n`);
+    return logPath;
+  } catch {
+    return null;
+  }
+}

apps/cli/src/help.ts

@@ -0,0 +1,145 @@
+/**
+ * Per-command help text.
+ *
+ * `shannon <command> --help`, `shannon <command> -h`, and `shannon help <command>`
+ * all render the matching command's usage, so a user can discover a command's
+ * flags without scanning the global help. The global help lives in index.ts.
+ */
+
+import { commandPrefix, getMode } from './mode.js';
+
+interface CommandHelp {
+  readonly usage: readonly string[];
+  readonly description: string;
+  readonly options?: readonly (readonly [string, string])[];
+  readonly examples?: readonly string[];
+}
+
+const YES_OPTION: readonly [string, string] = [
+  '-y, --yes',
+  'Skip the confirmation prompt (required for non-interactive use)',
+];
+const HELP_OPTION: readonly [string, string] = ['-h, --help', 'Show this help'];
+
+/**
+ * `start`'s flags, the single source rendered by both the per-command help here
+ * and the global help in index.ts, so the two can never drift.
+ */
+export const START_OPTIONS: readonly (readonly [string, string])[] = [
+  ['-u, --url <url>', 'Target URL (required)'],
+  ['-r, --repo <path>', 'Repository path (required)'],
+  ['-c, --config <path>', 'Configuration file (YAML)'],
+  ['-o, --output <path>', 'Copy deliverables to this directory after the run'],
+  ['-w, --workspace <name>', 'Named workspace (auto-resumes if it exists)'],
+  ['-f, --follow', 'Stream the scan log until it finishes'],
+  ['--pipeline-testing', 'Use minimal prompts for fast testing'],
+  ['--keep-container', 'Preserve the worker container after exit for log inspection'],
+];
+
+const COMMAND_HELP: Readonly<Record<string, CommandHelp>> = {
+  start: {
+    usage: ['start -u <url> -r <path> [options]'],
+    description: 'Start a pentest scan.',
+    examples: [
+      'start -u https://example.com -r ./my-repo',
+      'start -u https://example.com -r /path/to/repo -c config.yaml -w q1-audit',
+      'start -u https://example.com -r ./my-repo --follow',
+    ],
+  },
+  stop: {
+    usage: ['stop <workspace> [--yes]', 'stop --all [--yes]'],
+    description: 'Stop one scan by workspace, or every scan with --all (Temporal stays up).',
+    options: [['--all', 'Stop all running scans'], YES_OPTION],
+    examples: ['stop q1-audit', 'stop --all'],
+  },
+  reset: {
+    usage: ['reset'],
+    description: 'Stop everything and permanently remove all Temporal data and volumes.',
+  },
+  logs: {
+    usage: ['logs <workspace>'],
+    description: "Tail a scan's live log until it completes.",
+    examples: ['logs q1-audit'],
+  },
+  status: {
+    usage: ['status <workspace> [--json]'],
+    description:
+      "Show one scan's phase-by-phase progress, read live from Temporal. Watches and redraws until the scan finishes on a terminal; prints one frame when piped or already finished. With --json, prints a single machine-readable snapshot and exits.",
+    options: [['--json', 'Output a point-in-time snapshot as JSON, then exit']],
+    examples: ['status q1-audit', 'status q1-audit --json'],
+  },
+  scans: {
+    usage: ['scans [--json]'],
+    description: 'List completed scans and where each report lives.',
+    options: [['--json', 'Output the scan list as JSON']],
+    examples: ['scans', 'scans --json'],
+  },
+  build: {
+    usage: ['build [--no-cache]'],
+    description: 'Build the worker Docker image (local mode only).',
+    options: [['--no-cache', 'Build without using the Docker layer cache']],
+  },
+  setup: {
+    usage: ['setup'],
+    description: 'Configure provider credentials interactively (npx mode only).',
+  },
+  version: {
+    usage: ['version [--json]'],
+    description: 'Show the version. With --json, prints the version and mode as a machine-readable object.',
+    options: [['--json', 'Output the version and mode as JSON']],
+    examples: ['version', 'version --json'],
+  },
+};
+
+/** Commands that only exist in one mode; everything else is available in both. */
+const MODE_ONLY: Readonly<Record<string, 'local' | 'npx'>> = {
+  build: 'local',
+  setup: 'npx',
+};
+
+/** Whether a command has its own help page (and so responds to `--help`/`-h`). */
+export function isHelpableCommand(command: string): boolean {
+  return command in COMMAND_HELP;
+}
+
+/**
+ * User-facing command names available in the current mode, for "did you mean?"
+ * suggestions. Derived from the same table that backs per-command help, so the
+ * suggestion set can never drift from the commands that actually exist.
+ */
+export function availableCommands(): readonly string[] {
+  const mode = getMode();
+  const commands = Object.keys(COMMAND_HELP).filter((command) => (MODE_ONLY[command] ?? mode) === mode);
+  return [...commands, 'help'];
+}
+
+/** Print the help page for one command. No-op if the command has no page. */
+export function printCommandHelp(command: string): void {
+  const help = COMMAND_HELP[command];
+  if (!help) return;
+
+  const prefix = commandPrefix();
+  const baseOptions = command === 'start' ? START_OPTIONS : (help.options ?? []);
+  const options = [...baseOptions, HELP_OPTION];
+  const flagWidth = Math.max(...options.map(([flag]) => flag.length));
+
+  const lines: string[] = ['', help.description, '', 'USAGE'];
+  for (const line of help.usage) {
+    lines.push(`  ${prefix} ${line}`);
+  }
+
+  lines.push('', 'OPTIONS');
+  for (const [flag, desc] of options) {
+    lines.push(`  ${flag.padEnd(flagWidth)}  ${desc}`);
+  }
+
+  if (help.examples && help.examples.length > 0) {
+    lines.push('', 'EXAMPLES');
+    for (const example of help.examples) {
+      lines.push(`  ${prefix} ${example}`);
+    }
+  }
+
+  lines.push('');
+  console.log(lines.join('\n'));
+}

apps/cli/src/index.ts

@@ -9,15 +9,20 @@
  * in the current working directory.
  */
 
+import { ArgError, parseArgs, YES_FLAGS } from './args.js';
 import { build } from './commands/build.js';
 import { logs } from './commands/logs.js';
+import { reset } from './commands/reset.js';
+import { scans } from './commands/scans.js';
 import { setup } from './commands/setup.js';
 import { start } from './commands/start.js';
 import { status } from './commands/status.js';
 import { stop } from './commands/stop.js';
-import { uninstall } from './commands/uninstall.js';
-import { workspaces } from './commands/workspaces.js';
-import { getMode } from './mode.js';
+import { crash, fail, failUsage } from './errors.js';
+import { availableCommands, isHelpableCommand, printCommandHelp, START_OPTIONS } from './help.js';
+import { commandPrefix, getMode, isLocal } from './mode.js';
+import { displaySplash } from './splash.js';
+import { closestMatch } from './suggest.js';
 import { getVersion, getVersionLine } from './version.js';
 
 function blockSudo(): void {
@@ -25,27 +30,34 @@ function blockSudo(): void {
   const isRoot = process.geteuid?.() === 0;
   if (!isSudo && !isRoot) return;
 
+  const linuxHints =
+    process.platform === 'linux'
+      ? ['Configure Docker to run without sudo first:', 'https://docs.docker.com/engine/install/linux-postinstall']
+      : [];
+
   if (isSudo) {
-    console.error('ERROR: Shannon must not be run with sudo.');
-    console.error('Re-run this command as your normal user.');
-  } else {
-    console.error('ERROR: Shannon must not be run as the root user.');
-    console.error('Switch to a regular user account and re-run this command.');
+    fail('Shannon must not be run with sudo.', 'Re-run this command as your normal user.', ...linuxHints);
   }
-  if (process.platform === 'linux') {
-    console.error('Configure Docker to run without sudo first:');
-    console.error('https://docs.docker.com/engine/install/linux-postinstall');
-  }
-  process.exit(1);
+  fail(
+    'Shannon must not be run as the root user.',
+    'Switch to a regular user account and re-run this command.',
+    ...linuxHints,
+  );
 }
 
-function showHelp(): void {
+/** Render `start`'s flags for the global help, from the same source as `start --help`. */
+function renderStartOptions(): string {
+  const flagWidth = Math.max(...START_OPTIONS.map(([flag]) => flag.length));
+  return START_OPTIONS.map(([flag, desc]) => `  ${flag.padEnd(flagWidth)}  ${desc}`).join('\n');
+}
+
+function showHelp(withSplash: boolean): void {
   const mode = getMode();
-  const prefix = mode === 'local' ? './shannon' : 'npx @keygraph/shannon';
+  const prefix = commandPrefix();
 
-  console.log(`
-Shannon - AI Penetration Testing Framework
+  const header = withSplash ? '' : '\nShannon - AI Penetration Testing Framework\n';
 
+  console.log(`${header}
 Usage:${
     mode === 'local'
       ? ''
@@ -53,41 +65,33 @@ Usage:${
   ${prefix} setup                                       Configure credentials`
   }
   ${prefix} start --url <url> --repo <path> [options]   Start a pentest scan
-  ${prefix} stop [--clean] [--yes]                       Stop all running scans
-  ${prefix} workspaces                                   List all workspaces
+  ${prefix} stop <workspace> [--yes]                     Stop one scan
+  ${prefix} stop --all [--yes]                            Stop all scans (Temporal stays up)
+  ${prefix} reset                                        Stop everything and wipe all Temporal data
   ${prefix} logs <workspace>                             Show a scan's live log
-  ${prefix} status                                       Show running scans${
+  ${prefix} status <workspace> [--json]                  Live phase/agent progress of one scan
+  ${prefix} scans [--json]                                List completed scans and their reports${
     mode === 'local'
       ? `
   ${prefix} build [--no-cache]                           Build worker image`
-      : `
-  ${prefix} uninstall [--yes]                            Remove ~/.shannon/ and all data`
+      : ''
   }
-  ${prefix} version                                      Show version
+  ${prefix} version [--json]                             Show version
   ${prefix} help                                         Show this help
 
 Options for 'start':
-  -u, --url <url>           Target URL (required)
-  -r, --repo <path>         Repository path${mode === 'local' ? ' or bare name' : ''} (required)
-  -c, --config <path>       Configuration file (YAML)
-  -o, --output <path>       Copy deliverables to this directory after run
-  -w, --workspace <name>    Named workspace (auto-resumes if exists)
-      --pipeline-testing    Use minimal prompts for fast testing
-      --debug               Preserve worker container after exit for log inspection
+${renderStartOptions()}
 
 Examples:
-  ${prefix} start -u https://example.com -r ${mode === 'local' ? 'my-repo' : './my-repo'}
+  ${prefix} start -u https://example.com -r ./my-repo
   ${prefix} start -u https://example.com -r /path/to/repo -c config.yaml -w q1-audit
   ${prefix} logs q1-audit
-  ${prefix} stop --clean
-${
-  mode === 'local'
-    ? `
-State directory: ./workspaces/`
-    : `
-State directory: ~/.shannon/`
-}
-Monitor scans at http://localhost:8233
+  ${prefix} stop q1-audit
+  ${prefix} reset
+
+Run '${prefix} <command> --help' for help on a specific command.
+
+Docs & source: https://github.com/KeygraphHQ/shannon
 `);
 }
 
@@ -98,150 +102,168 @@ interface ParsedStartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  debug: boolean;
+  keepContainer: boolean;
+  follow: boolean;
 }
 
 function parseStartArgs(argv: string[]): ParsedStartArgs {
-  let url = '';
-  let repo = '';
-  let config: string | undefined;
-  let workspace: string | undefined;
-  let output: string | undefined;
-  let pipelineTesting = false;
-  let debug = false;
+  const { flags, values } = parseArgs(argv, {
+    values: {
+      url: ['-u', '--url'],
+      repo: ['-r', '--repo'],
+      config: ['-c', '--config'],
+      output: ['-o', '--output'],
+      workspace: ['-w', '--workspace'],
+    },
+    booleans: {
+      pipelineTesting: ['--pipeline-testing'],
+      keepContainer: ['--keep-container'],
+      follow: ['-f', '--follow'],
+    },
+  });
 
-  for (let i = 0; i < argv.length; i++) {
-    const arg = argv[i];
-    const next = argv[i + 1];
-
-    switch (arg) {
-      case '-u':
-      case '--url':
-        if (next && !next.startsWith('-')) {
-          url = next;
-          i++;
-        }
-        break;
-      case '-r':
-      case '--repo':
-        if (next && !next.startsWith('-')) {
-          repo = next;
-          i++;
-        }
-        break;
-      case '-c':
-      case '--config':
-        if (next && !next.startsWith('-')) {
-          config = next;
-          i++;
-        }
-        break;
-      case '-w':
-      case '--workspace':
-        if (next && !next.startsWith('-')) {
-          workspace = next;
-          i++;
-        }
-        break;
-      case '-o':
-      case '--output':
-        if (next && !next.startsWith('-')) {
-          output = next;
-          i++;
-        }
-        break;
-      case '--pipeline-testing':
-        pipelineTesting = true;
-        break;
-      case '--debug':
-        debug = true;
-        break;
-      default:
-        console.error(`Unknown option: ${arg}`);
-        console.error(`Run "${getMode() === 'local' ? './shannon' : 'npx @keygraph/shannon'} help" for usage`);
-        process.exit(1);
-    }
+  const url = values.url ?? '';
+  const repo = values.repo ?? '';
+  if (!url || !repo) {
+    failUsage('--url and --repo are required', `Usage: ${commandPrefix()} start -u <url> -r <path>`);
   }
 
-  if (!url || !repo) {
-    console.error('ERROR: --url and --repo are required');
-    console.error(`Usage: ${getMode() === 'local' ? './shannon' : 'npx @keygraph/shannon'} start -u <url> -r <path>`);
-    process.exit(1);
+  try {
+    new URL(url);
+  } catch {
+    failUsage(`invalid --url: ${url}`);
   }
 
   return {
     url,
     repo,
-    pipelineTesting,
-    debug,
-    ...(config && { config }),
-    ...(workspace && { workspace }),
-    ...(output && { output }),
+    pipelineTesting: !!flags.pipelineTesting,
+    keepContainer: !!flags.keepContainer,
+    follow: !!flags.follow,
+    ...(values.config && { config: values.config }),
+    ...(values.workspace && { workspace: values.workspace }),
+    ...(values.output && { output: values.output }),
   };
 }
 
 // === Main Dispatch ===
 
-blockSudo();
+async function main(): Promise<void> {
+  // A reader that closes early (e.g. `shannon logs my-scan | head`) makes writes
+  // to stdout raise EPIPE. That's normal for a piped CLI, not a crash — exit quietly
+  // instead of letting Node dump an unhandled-error stack trace.
+  process.stdout.on('error', (err: NodeJS.ErrnoException) => {
+    if (err.code === 'EPIPE') process.exit(0);
+    throw err;
+  });
 
-const args = process.argv.slice(2);
-const command = args[0];
+  blockSudo();
 
-switch (command) {
-  case 'start': {
-    const parsed = parseStartArgs(args.slice(1));
-    await start({ ...parsed, version: getVersion() });
-    break;
+  const args = process.argv.slice(2);
+  const command = args[0];
+  const rest = args.slice(1);
+
+  if (command === undefined || command === 'help' || command === '--help' || command === '-h') {
+    const topic = rest[0];
+    if (topic && isHelpableCommand(topic)) {
+      printCommandHelp(topic);
+    } else {
+      const bare = command === undefined;
+      if (bare) displaySplash(isLocal() ? undefined : getVersion());
+      showHelp(bare);
+    }
+    return;
   }
-  case 'stop':
-    stop(args.includes('--clean'), args.includes('--yes') || args.includes('-y'));
-    break;
-  case 'logs': {
-    const workspaceId = args[1];
-    if (!workspaceId) {
-      console.error('ERROR: Workspace ID is required');
-      console.error(`Usage: ${getMode() === 'local' ? './shannon' : 'npx @keygraph/shannon'} logs <workspace>`);
-      process.exit(1);
-    }
-    logs(workspaceId);
-    break;
+
+  // Reachable from any invocation: `-h`/`--help` anywhere wins over the rest of the line.
+  if (isHelpableCommand(command) && (rest.includes('-h') || rest.includes('--help'))) {
+    printCommandHelp(command);
+    return;
   }
-  case 'workspaces':
-    workspaces(getVersion());
-    break;
-  case 'status':
-    status();
-    break;
-  case 'setup':
-    if (getMode() === 'local') {
-      console.error('ERROR: setup is only available in npx mode. In local mode, use .env');
-      process.exit(1);
+
+  switch (command) {
+    case 'start': {
+      const parsed = parseStartArgs(rest);
+      await start({ ...parsed, version: getVersion() });
+      break;
     }
-    setup();
-    break;
-  case 'build':
-    build(args.includes('--no-cache'), getVersion());
-    break;
-  case 'uninstall':
-    if (getMode() === 'local') {
-      console.error('ERROR: uninstall is only available in npx mode.');
-      process.exit(1);
+    case 'stop': {
+      const { flags, positionals } = parseArgs(rest, {
+        booleans: { all: ['--all'], yes: YES_FLAGS },
+        maxPositionals: 1,
+      });
+      await stop({ all: !!flags.all, yes: !!flags.yes, ...(positionals[0] && { workspace: positionals[0] }) });
+      break;
     }
-    uninstall(args.includes('--yes') || args.includes('-y'));
-    break;
-  case 'version':
-  case '--version':
-  case '-v':
-    console.log(getVersionLine());
-    break;
-  case 'help':
-  case '--help':
-  case '-h':
-  case undefined:
-    showHelp();
-    break;
-  default:
-    console.error(`Unknown command: ${command}`);
-    showHelp();
-    process.exit(1);
+    case 'reset': {
+      // reset is all-or-nothing; a stray name likely means the user wanted `stop <name>`.
+      parseArgs(rest, {
+        positionalHint: 'reset takes no workspace argument. To stop one scan, use: stop <name>',
+      });
+      await reset();
+      break;
+    }
+    case 'logs': {
+      const { positionals } = parseArgs(rest, { maxPositionals: 1 });
+      const workspaceId = positionals[0];
+      if (!workspaceId) {
+        failUsage('Workspace ID is required', `Usage: ${commandPrefix()} logs <workspace>`);
+      }
+      logs(workspaceId);
+      break;
+    }
+    case 'status': {
+      const { flags, positionals } = parseArgs(rest, { booleans: { json: ['--json'] }, maxPositionals: 1 });
+      const workspaceId = positionals[0];
+      if (!workspaceId) {
+        failUsage('Workspace is required', `Usage: ${commandPrefix()} status <workspace> [--json]`);
+      }
+      await status(workspaceId, { json: !!flags.json });
+      break;
+    }
+    case 'scans': {
+      const { flags } = parseArgs(rest, { booleans: { json: ['--json'] } });
+      scans({ json: !!flags.json });
+      break;
+    }
+    case 'setup':
+      if (getMode() === 'local') {
+        fail('setup is only available in npx mode. In local mode, use .env');
+      }
+      parseArgs(rest, {});
+      await setup();
+      break;
+    case 'build': {
+      const { flags } = parseArgs(rest, { booleans: { noCache: ['--no-cache'] } });
+      build(!!flags.noCache, getVersion());
+      break;
+    }
+    case 'version':
+    case '--version':
+    case '-v': {
+      const { flags } = parseArgs(rest, { booleans: { json: ['--json'] } });
+      if (flags.json) {
+        console.log(JSON.stringify({ version: getVersion(), mode: getMode() }, null, 2));
+      } else {
+        console.log(getVersionLine());
+      }
+      break;
+    }
+    default: {
+      const prefix = commandPrefix();
+      const suggestion = closestMatch(command, availableCommands());
+      const hints = [
+        ...(suggestion ? [`Did you mean '${suggestion}'?`] : []),
+        `Run '${prefix} help' to see available commands.`,
+      ];
+      failUsage(`Unknown command: ${command}`, ...hints);
+    }
+  }
 }
+
+main().catch((err) => {
+  if (err instanceof ArgError) {
+    failUsage(err.message, `Run "${commandPrefix()} help" for usage`);
+  }
+  crash(err);
+});

apps/cli/src/mode.ts

@@ -24,6 +24,11 @@ export function isLocal(): boolean {
   return getMode() === 'local';
 }
 
+/** The invocation prefix for the current mode, so help and hints point at a runnable command. */
+export function commandPrefix(): string {
+  return getMode() === 'local' ? './shannon' : 'npx @keygraph/shannon';
+}
+
 export function isDevMode(): boolean {
   return process.env.SHANNON_DEV === '1';
 }

apps/cli/src/model-spec.ts

@@ -6,24 +6,35 @@
  * rule are duplicated here deliberately and must stay in sync.
  */
 
-/** Providers Shannon can currently reach. Each is a pi-ai provider id. */
-export const SUPPORTED_PROVIDERS = ['anthropic', 'openai', 'xai', 'amazon-bedrock'] as const;
+/**
+ * Providers Shannon curates with their own credential variables, config sections,
+ * and setup flows. Any other pi provider is reachable via the generic credential
+ * path. Mirrors CURATED_PROVIDERS in apps/worker/src/ai/models.ts.
+ */
+export const CURATED_PROVIDERS = ['anthropic', 'openai', 'xai', 'amazon-bedrock'] as const;
 
-export type ProviderId = (typeof SUPPORTED_PROVIDERS)[number];
+export type CuratedProviderId = (typeof CURATED_PROVIDERS)[number];
+
+export function isCuratedProvider(value: string): value is CuratedProviderId {
+  return (CURATED_PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Generic API key, honored for any provider Shannon does not curate. Mirrors the worker. */
+export const GENERIC_API_KEY_ENV = 'SHANNON_AI_API_KEY';
 
 /**
- * Env vars carrying each provider's API key, in precedence order. Any one of them
- * satisfies the provider. Mirrors PROVIDER_API_KEY_ENV in apps/worker/src/ai/models.ts.
+ * Env vars carrying each curated provider's API key, in precedence order. Any one of
+ * them satisfies the provider. Mirrors PROVIDER_API_KEY_ENV in apps/worker/src/ai/models.ts.
  */
-export const PROVIDER_API_KEY_ENV: Readonly<Record<ProviderId, readonly string[]>> = {
+export const PROVIDER_API_KEY_ENV: Readonly<Record<CuratedProviderId, readonly string[]>> = {
   anthropic: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'],
   openai: ['OPENAI_API_KEY'],
   xai: ['XAI_API_KEY'],
   'amazon-bedrock': ['AWS_BEARER_TOKEN_BEDROCK'],
 };
 
-/** Additional env vars a provider requires beyond its API key. All must be set. */
-export const PROVIDER_EXTRA_ENV: Readonly<Record<ProviderId, readonly string[]>> = {
+/** Additional env vars a curated provider requires beyond its API key. All must be set. */
+export const PROVIDER_EXTRA_ENV: Readonly<Record<CuratedProviderId, readonly string[]>> = {
   anthropic: [],
   openai: [],
   xai: [],
@@ -31,7 +42,7 @@ export const PROVIDER_EXTRA_ENV: Readonly<Record<ProviderId, readonly string[]>>
 };
 
 /** Human-readable credential requirement, used in "nothing configured" errors. */
-export const PROVIDER_CREDENTIAL_HINT: Readonly<Record<ProviderId, string>> = {
+export const PROVIDER_CREDENTIAL_HINT: Readonly<Record<CuratedProviderId, string>> = {
   anthropic: 'ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN)',
   openai: 'OPENAI_API_KEY',
   xai: 'XAI_API_KEY',
@@ -51,18 +62,15 @@ export const OPENAI_FORMATS = ['chat-completions', 'responses'] as const;
 export type OpenAiFormat = (typeof OPENAI_FORMATS)[number];
 
 export interface ModelSpec {
-  providerId: ProviderId;
+  providerId: string;
   modelId: string;
 }
 
-function isSupportedProvider(value: string): value is ProviderId {
-  return (SUPPORTED_PROVIDERS as readonly string[]).includes(value);
-}
-
 /**
  * Parse a `<provider>:<model-id>` spec. Splits on the first colon only, so colons
  * inside a model ID survive (`amazon-bedrock:us.anthropic.claude-opus-4-5-20251101-v1:0`).
- * Returns an error string rather than throwing, for the CLI's validation flow.
+ * The provider id is passed through as given — the worker's preflight validates it
+ * against pi. Returns an error string rather than throwing, for the CLI's flow.
  */
 export function parseModelSpec(spec: string): ModelSpec | string {
   const trimmed = spec.trim();
@@ -74,9 +82,6 @@ export function parseModelSpec(spec: string): ModelSpec | string {
   const modelId = trimmed.slice(separator + 1).trim();
   if (!providerId || !modelId) return malformed;
 
-  if (!isSupportedProvider(providerId)) {
-    return `Unsupported provider "${providerId}" in SHANNON_AI_MODEL. Supported providers: ${SUPPORTED_PROVIDERS.join(', ')}`;
-  }
   return { providerId, modelId };
 }
 

apps/cli/src/paths.ts

@@ -1,13 +1,27 @@
 /**
  * Path resolution for --repo and --config arguments.
  *
- * Local mode supports bare repo names (e.g. "my-repo" → ./repos/my-repo).
- * Both modes resolve relative paths against CWD.
+ * Both --repo and --config are filesystem paths, absolute or relative to CWD.
  */
 
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { isLocal } from './mode.js';
+import { fail } from './errors.js';
+
+/**
+ * Expand a leading `~` or `~/` to the home directory. The shell skips this in the
+ * `--flag=~/x` form (the tilde is not at the word start), so it must be done here.
+ */
+export function expandHome(inputPath: string): string {
+  if (inputPath === '~') {
+    return os.homedir();
+  }
+  if (inputPath.startsWith('~/')) {
+    return path.join(os.homedir(), inputPath.slice(2));
+  }
+  return inputPath;
+}
 
 export interface MountPair {
   hostPath: string;
@@ -23,10 +37,10 @@ export interface MountPair {
 export const INTERNAL_DIR = '.shannon';
 
 /**
- * Filename of the human-facing final report surfaced at the run directory root.
- * Must match FINAL_REPORT_FILENAME in the worker package.
+ * Filename of the human-facing PDF report surfaced at the run directory root.
+ * Must match FINAL_REPORT_PDF_FILENAME in the worker package.
  */
-export const FINAL_REPORT_FILENAME = 'Security-Assessment-Report.md';
+export const FINAL_REPORT_PDF_FILENAME = 'Security-Assessment-Report.pdf';
 
 /**
  * Resolve a run-directory file (e.g. session.json, workflow.log), preferring the
@@ -47,36 +61,18 @@ export function resolveRunFile(runDir: string, filename: string): string {
 }
 
 /**
- * Resolve --repo to absolute path and container mount.
- * Dev mode: bare names (no / or . prefix) check ./repos/<name> first.
+ * Resolve --repo to an absolute path and container mount. The argument is a
+ * filesystem path, absolute or relative to CWD.
  */
 export function resolveRepo(repoArg: string): MountPair {
-  let hostPath: string;
-
-  if (isLocal() && !repoArg.startsWith('/') && !repoArg.startsWith('.')) {
-    // Bare name — check ./repos/<name> for backward compatibility
-    const barePath = path.resolve('repos', repoArg);
-    if (fs.existsSync(barePath)) {
-      hostPath = barePath;
-    } else {
-      console.error(`ERROR: Repository not found at ./repos/${repoArg}`);
-      console.error('');
-      console.error('Place your target repository under the ./repos/ directory,');
-      console.error('or pass an absolute/relative path: -r /path/to/repo');
-      process.exit(1);
-    }
-  } else {
-    hostPath = path.resolve(repoArg);
-  }
+  const hostPath = path.resolve(expandHome(repoArg));
 
   if (!fs.existsSync(hostPath)) {
-    console.error(`ERROR: Repository not found: ${hostPath}`);
-    process.exit(1);
+    fail(`Repository not found: ${hostPath}`);
   }
 
   if (!fs.statSync(hostPath).isDirectory()) {
-    console.error(`ERROR: Not a directory: ${hostPath}`);
-    process.exit(1);
+    fail(`Not a directory: ${hostPath}`);
   }
 
   const basename = path.basename(hostPath);
@@ -90,16 +86,14 @@ export function resolveRepo(repoArg: string): MountPair {
  * Resolve --config to absolute path and container mount.
  */
 export function resolveConfig(configArg: string): MountPair {
-  const hostPath = path.resolve(configArg);
+  const hostPath = path.resolve(expandHome(configArg));
 
   if (!fs.existsSync(hostPath)) {
-    console.error(`ERROR: Config file not found: ${hostPath}`);
-    process.exit(1);
+    fail(`Config file not found: ${hostPath}`);
   }
 
   if (!fs.statSync(hostPath).isFile()) {
-    console.error(`ERROR: Not a file: ${hostPath}`);
-    process.exit(1);
+    fail(`Not a file: ${hostPath}`);
   }
 
   const basename = path.basename(hostPath);

apps/cli/src/scan/derive.ts

@@ -0,0 +1,155 @@
+/**
+ * Pure derivation of a scan's per-agent and per-phase state from its Temporal snapshot.
+ *
+ * This is the single source of truth for "what state is each agent in" — both the
+ * human progress tree (render.ts) and the machine-readable snapshot (status-json.ts)
+ * consume it, so the two views can never disagree about whether an agent is running,
+ * skipped, or still pending. No glyphs, no color, no formatting live here.
+ */
+
+import type { RunningAgent } from '../temporal-client.js';
+import { agentClass, PIPELINE, type PipelineState } from './pipeline.js';
+import type { RenderInput } from './render.js';
+
+export type RunState = 'pending' | 'running' | 'completed' | 'failed' | 'skipped';
+
+/** One agent's resolved state plus the raw metrics/timing a consumer needs to present it. Null metrics
+ *  mean the value doesn't apply to the current state (e.g. duration only for completed agents). */
+export interface DerivedAgent {
+  readonly name: string;
+  readonly label: string;
+  readonly state: RunState;
+  readonly durationMs: number | null;
+  readonly runningElapsedMs: number | null;
+  readonly attempt: number | null;
+  readonly error?: string;
+}
+
+export interface DerivedPhase {
+  readonly key: string;
+  readonly label: string;
+  readonly parallel: boolean;
+  readonly state: RunState;
+  readonly agents: readonly DerivedAgent[];
+}
+
+/** Terminal = anything other than an open, running execution. */
+export function isTerminal(status: string): boolean {
+  return status !== 'RUNNING' && status !== 'UNSPECIFIED';
+}
+
+function isFailedAgent(name: string, state: PipelineState | null): boolean {
+  return !!state && (state.failedAgent === name || state.failedPipelines.some((f) => f.vulnType === agentClass(name)));
+}
+
+/** An agent has entered play once it is running, has metrics, or has failed. */
+function isAgentActive(name: string, state: PipelineState | null, running: Set<string>): boolean {
+  return running.has(name) || !!state?.agentMetrics[name] || isFailedAgent(name, state);
+}
+
+/**
+ * Resolve one agent's state. "Ran" is signalled by a metrics entry, not by
+ * completedAgents — the workflow lists conditionally-skipped agents (e.g. exploit
+ * agents when there is nothing to exploit) as completed but records no metrics for
+ * them. `resolved` is true once we've moved past this agent's phase (the scan is
+ * terminal, or a later phase is already active), at which point a metric-less,
+ * non-running agent is skipped rather than still pending.
+ */
+function agentState(name: string, state: PipelineState | null, running: Set<string>, resolved: boolean): RunState {
+  if (running.has(name)) return 'running';
+  if (isFailedAgent(name, state)) return 'failed';
+  if (state?.agentMetrics[name]) return 'completed';
+  return resolved ? 'skipped' : 'pending';
+}
+
+function agentError(name: string, state: PipelineState | null, byAgent: Map<string, RunningAgent>): string | undefined {
+  const failed = state?.failedPipelines.find((f) => f.vulnType === agentClass(name));
+  return (
+    failed?.error ??
+    byAgent.get(name)?.lastFailure ??
+    (state?.failedAgent === name ? (state.error ?? undefined) : undefined)
+  );
+}
+
+/** Scan wall-clock elapsed ms: recorded duration for a closed scan, live elapsed for a running one. */
+export function scanElapsedMs(input: RenderInput, now: number): number | undefined {
+  if (isTerminal(input.temporalStatus)) {
+    if (input.state?.summary) return input.state.summary.totalDurationMs;
+    if (input.endedAt !== undefined && input.startedAt !== undefined) return input.endedAt - input.startedAt;
+    return undefined;
+  }
+  return input.startedAt !== undefined ? now - input.startedAt : undefined;
+}
+
+/** Collapse a phase's agent states into a single state for the phase line. */
+export function phaseGlyphState(states: readonly RunState[]): RunState {
+  if (states.some((s) => s === 'running')) return 'running';
+  if (states.some((s) => s === 'failed')) return 'failed';
+  if (states.every((s) => s === 'skipped')) return 'skipped';
+  if (states.every((s) => s === 'completed' || s === 'skipped')) return 'completed';
+  if (states.some((s) => s === 'completed')) return 'running';
+  return 'pending';
+}
+
+/**
+ * Compute each agent's RunState. This is the drift-prone part shared by every view.
+ *
+ * The pipeline is sequential across phases: the last phase with any active agent is the
+ * frontier. Earlier phases with nothing active were skipped (e.g. exploitation when no
+ * class had anything to exploit), not still pending.
+ */
+export function deriveAgentStates(input: RenderInput): Map<string, RunState> {
+  const runningSet = new Set(input.running.map((r) => r.agent));
+  const terminal = isTerminal(input.temporalStatus);
+
+  let frontier = -1;
+  PIPELINE.forEach((phase, idx) => {
+    if (phase.agents.some((a) => isAgentActive(a.name, input.state, runningSet))) frontier = idx;
+  });
+
+  const states = new Map<string, RunState>();
+  for (const [phaseIdx, phase] of PIPELINE.entries()) {
+    const resolved = terminal || phaseIdx < frontier;
+    for (const agent of phase.agents) {
+      states.set(agent.name, agentState(agent.name, input.state, runningSet, resolved));
+    }
+  }
+  return states;
+}
+
+/**
+ * Full structured view of the pipeline: every agent's state plus the raw
+ * metrics/timing needed to present it, and each phase's collapsed state.
+ */
+export function derivePipeline(input: RenderInput, now: number): DerivedPhase[] {
+  const states = deriveAgentStates(input);
+  const byAgent = new Map(input.running.map((r) => [r.agent, r]));
+
+  return PIPELINE.map((phase) => {
+    const agents = phase.agents.map((a): DerivedAgent => {
+      const state = states.get(a.name) ?? 'pending';
+      const metrics = input.state?.agentMetrics[a.name];
+      const runner = byAgent.get(a.name);
+      const error = agentError(a.name, input.state, byAgent);
+      return {
+        name: a.name,
+        label: a.label,
+        state,
+        durationMs: state === 'completed' && metrics ? metrics.durationMs : null,
+        runningElapsedMs: state === 'running' && runner?.startedAt !== undefined ? now - runner.startedAt : null,
+        attempt: state === 'running' && runner ? runner.attempt : null,
+        ...(error !== undefined && { error }),
+      };
+    });
+
+    return {
+      key: phase.key,
+      label: phase.label,
+      parallel: phase.parallel,
+      state: phaseGlyphState(agents.map((ag) => ag.state)),
+      agents,
+    };
+  });
+}
+
+export { agentError };

apps/cli/src/scan/pipeline.ts

@@ -0,0 +1,123 @@
+/**
+ * Static description of the Shannon scan pipeline, plus the worker types the CLI
+ * reads back from Temporal.
+ *
+ * The CLI cannot import from the worker package, so this mirrors it. Keep in sync with:
+ *   - apps/worker/src/types/agents.ts        (agent names / ordering)
+ *   - apps/worker/src/session-manager.ts     (phase membership)
+ *   - apps/worker/src/temporal/activities.ts (the run*Agent activity names → `activityType`)
+ *   - apps/worker/src/temporal/shared.ts     (PipelineState / PipelineSummary)
+ *   - apps/worker/src/types/metrics.ts       (AgentMetrics)
+ */
+
+export interface AgentSpec {
+  /** Canonical agent name as it appears in PipelineState.completedAgents / agentMetrics. */
+  readonly name: string;
+  /** Short label for the progress tree. */
+  readonly label: string;
+  /** Temporal activity type name — how a running agent shows up in pendingActivities. */
+  readonly activityType: string;
+}
+
+export interface PhaseSpec {
+  readonly key: string;
+  readonly label: string;
+  readonly parallel: boolean;
+  readonly agents: readonly AgentSpec[];
+}
+
+/** The pipeline phases in execution order, each with its agents. */
+export const PIPELINE: readonly PhaseSpec[] = [
+  {
+    // Preflight login check. Only authenticated scans record metrics here; a non-auth scan
+    // records none, so it renders as skipped — like Exploitation when nothing is exploitable.
+    key: 'auth-validation',
+    label: 'Authentication',
+    parallel: false,
+    agents: [{ name: 'validate-authentication', label: 'auth', activityType: 'runAuthenticationValidation' }],
+  },
+  {
+    key: 'pre-recon',
+    label: 'Pre-Recon',
+    parallel: false,
+    agents: [{ name: 'pre-recon', label: 'pre-recon', activityType: 'runPreReconAgent' }],
+  },
+  {
+    key: 'recon',
+    label: 'Recon',
+    parallel: false,
+    agents: [{ name: 'recon', label: 'recon', activityType: 'runReconAgent' }],
+  },
+  {
+    key: 'vulnerability-analysis',
+    label: 'Vulnerability Analysis',
+    parallel: true,
+    agents: [
+      { name: 'injection-vuln', label: 'injection', activityType: 'runInjectionVulnAgent' },
+      { name: 'xss-vuln', label: 'xss', activityType: 'runXssVulnAgent' },
+      { name: 'auth-vuln', label: 'auth', activityType: 'runAuthVulnAgent' },
+      { name: 'ssrf-vuln', label: 'ssrf', activityType: 'runSsrfVulnAgent' },
+      { name: 'authz-vuln', label: 'authz', activityType: 'runAuthzVulnAgent' },
+    ],
+  },
+  {
+    key: 'exploitation',
+    label: 'Exploitation',
+    parallel: true,
+    agents: [
+      { name: 'injection-exploit', label: 'injection', activityType: 'runInjectionExploitAgent' },
+      { name: 'xss-exploit', label: 'xss', activityType: 'runXssExploitAgent' },
+      { name: 'auth-exploit', label: 'auth', activityType: 'runAuthExploitAgent' },
+      { name: 'ssrf-exploit', label: 'ssrf', activityType: 'runSsrfExploitAgent' },
+      { name: 'authz-exploit', label: 'authz', activityType: 'runAuthzExploitAgent' },
+    ],
+  },
+  {
+    key: 'reporting',
+    label: 'Reporting',
+    parallel: false,
+    agents: [{ name: 'report', label: 'report', activityType: 'runReportAgent' }],
+  },
+];
+
+/** Temporal activity type name → canonical agent name, for mapping pendingActivities. */
+export const ACTIVITY_TO_AGENT: Readonly<Record<string, string>> = Object.fromEntries(
+  PIPELINE.flatMap((phase) => phase.agents.map((agent) => [agent.activityType, agent.name])),
+);
+
+/** The vuln/exploit class of an agent (e.g. "authz-vuln" → "authz"), for failedPipelines matching. */
+export function agentClass(name: string): string {
+  return name.replace(/-(vuln|exploit)$/, '');
+}
+
+// === Worker types read back from Temporal (mirror of shared.ts / metrics.ts) ===
+
+export interface AgentMetrics {
+  readonly durationMs: number;
+  readonly costUsd: number | null;
+  readonly numTurns: number | null;
+  readonly model?: string;
+  readonly skipped?: boolean;
+}
+
+export interface PipelineSummary {
+  readonly totalCostUsd: number;
+  readonly totalDurationMs: number; // Wall-clock (end - start)
+  readonly totalTurns: number;
+  readonly agentCount: number;
+}
+
+export type PipelineStatus = 'running' | 'completed' | 'failed' | 'cancelled' | 'partial';
+
+export interface PipelineState {
+  readonly status: PipelineStatus;
+  readonly currentPhase: string | null;
+  readonly currentAgent: string | null;
+  readonly completedAgents: string[];
+  readonly failedPipelines: { vulnType: string; error: string }[];
+  readonly failedAgent: string | null;
+  readonly error: string | null;
+  readonly startTime: number;
+  readonly agentMetrics: Record<string, AgentMetrics>;
+  readonly summary: PipelineSummary | null;
+}

apps/cli/src/scan/render.ts

@@ -0,0 +1,248 @@
+/**
+ * Renders a scan's Temporal state into the terminal progress tree.
+ *
+ * The same PipelineState drives both the live view (from the getProgress query) and
+ * the final view (from the workflow result); the running-agents overlay (from
+ * pendingActivities) supplies the in-flight set and retry counts the state lacks.
+ * Colors and Unicode glyphs are gated by the caller so the frame degrades off a TTY.
+ */
+
+import { BOLD, DIM, GOLD, paint, RED, YELLOW } from '../colors.js';
+import { commandPrefix } from '../mode.js';
+import type { RunningAgent } from '../temporal-client.js';
+import { agentError, deriveAgentStates, isTerminal, phaseGlyphState, type RunState, scanElapsedMs } from './derive.js';
+import { PIPELINE, type PipelineState } from './pipeline.js';
+
+export interface RenderInput {
+  readonly workspace: string;
+  /** Temporal workflow id backing this scan (differs from workspace on a resume); used for the dashboard link. */
+  readonly workflowId?: string;
+  /** Temporal WorkflowExecutionStatusName: RUNNING | COMPLETED | FAILED | CANCELLED | TERMINATED | … */
+  readonly temporalStatus: string;
+  /** Progress (live) or result (terminal). Null when unavailable, e.g. a hard failure with no result. */
+  readonly state: PipelineState | null;
+  readonly running: readonly RunningAgent[];
+  readonly startedAt?: number;
+  readonly endedAt?: number;
+  /** Failure text when a failed scan has no readable state. */
+  readonly failureMessage?: string;
+}
+
+export interface RenderOptions {
+  readonly now: number;
+  readonly color: boolean;
+  readonly unicode: boolean;
+  /** True for the live view (adds a watch footer); false for the final/one-shot frame. */
+  readonly live: boolean;
+  /** Animation tick — advances the running-agent spinner. Ignored for static frames. */
+  readonly frame: number;
+}
+
+const COLORS = {
+  red: RED,
+  gold: GOLD,
+  yellow: YELLOW,
+  dim: DIM,
+  bold: BOLD,
+} as const;
+
+// === Formatting ===
+
+function formatDuration(ms: number): string {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  const secs = seconds % 60;
+
+  if (hours > 0) return `${hours}h ${minutes}m`;
+  if (minutes > 0) return `${minutes}m ${secs}s`;
+  return `${secs}s`;
+}
+
+function truncate(text: string, max: number): string {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= max ? flat : `${flat.slice(0, max - 1)}…`;
+}
+
+/** Temporal Web UI, published by compose on 8233; deep-links to the workflow when its id is known. */
+function temporalDashboardUrl(workflowId: string | undefined): string {
+  const base = 'http://localhost:8233';
+  return workflowId ? `${base}/namespaces/default/workflows/${workflowId}` : base;
+}
+
+// === Glyphs & status ===
+
+const GLYPH_UNICODE: Record<RunState, string> = {
+  pending: '○',
+  running: '⟳',
+  completed: '●',
+  failed: '✗',
+  skipped: '·',
+};
+const GLYPH_ASCII: Record<RunState, string> = {
+  pending: '.',
+  running: '>',
+  completed: '+',
+  failed: 'x',
+  skipped: '-',
+};
+const STATE_COLOR: Record<RunState, string> = {
+  pending: COLORS.dim,
+  running: COLORS.gold,
+  completed: COLORS.gold,
+  failed: COLORS.red,
+  skipped: COLORS.dim,
+};
+
+/** Braille spinner frames for running agents — the clack loader style. */
+const SPINNER_FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'] as const;
+
+function glyph(state: RunState, opts: RenderOptions): string {
+  if (state === 'running' && opts.unicode) {
+    const spin = SPINNER_FRAMES[opts.frame % SPINNER_FRAMES.length] ?? SPINNER_FRAMES[0];
+    return paint(spin, STATE_COLOR.running, opts.color);
+  }
+  const symbol = opts.unicode ? GLYPH_UNICODE[state] : GLYPH_ASCII[state];
+  return paint(symbol, STATE_COLOR[state], opts.color);
+}
+
+/** Badge text + color for the scan as a whole, preferring the workflow's own status when known. */
+function statusBadge(input: RenderInput, opts: RenderOptions): string {
+  const workflowStatus = input.state?.status;
+  if (!isTerminal(input.temporalStatus)) return paint('running', COLORS.gold, opts.color);
+  if (workflowStatus === 'partial') return paint('partial', COLORS.yellow, opts.color);
+  if (input.temporalStatus === 'COMPLETED') return paint('completed', COLORS.gold, opts.color);
+  if (input.temporalStatus === 'TERMINATED') return paint('stopped', COLORS.yellow, opts.color);
+  if (input.temporalStatus === 'CANCELLED' || input.temporalStatus === 'CANCELED') {
+    return paint('cancelled', COLORS.yellow, opts.color);
+  }
+  if (input.temporalStatus === 'TIMED_OUT') return paint('timed out', COLORS.red, opts.color);
+  return paint('FAILED', COLORS.red, opts.color);
+}
+
+// === Line builders ===
+
+function agentMeta(
+  state: RunState,
+  metrics: { durationMs: number } | undefined,
+  runner: RunningAgent | undefined,
+  error: string | undefined,
+  opts: RenderOptions,
+): string {
+  if (state === 'completed') {
+    const duration = metrics?.durationMs != null ? formatDuration(metrics.durationMs) : 'done';
+    return paint(duration, COLORS.dim, opts.color);
+  }
+  if (state === 'running') {
+    const parts = ['running'];
+    if (runner?.startedAt !== undefined) parts.push(formatDuration(opts.now - runner.startedAt));
+    if (runner && runner.attempt > 1) parts.push(`retry ${runner.attempt}`);
+    return paint(parts.join(' · '), COLORS.gold, opts.color);
+  }
+  if (state === 'failed') {
+    const detail = error ? ` · ${truncate(error, 46)}` : '';
+    return paint(`failed${detail}`, COLORS.red, opts.color);
+  }
+  if (state === 'skipped') return paint('skipped', COLORS.dim, opts.color);
+  return paint('queued', COLORS.dim, opts.color);
+}
+
+function phaseMeta(states: readonly RunState[], inPlay: number, parallel: boolean, opts: RenderOptions): string {
+  if (states.every((s) => s === 'pending')) return paint('pending', COLORS.dim, opts.color);
+  if (states.every((s) => s === 'skipped')) return paint('skipped', COLORS.dim, opts.color);
+  if (states.some((s) => s === 'failed') && !states.some((s) => s === 'running')) {
+    return paint('failed', COLORS.red, opts.color);
+  }
+  if (!parallel) return '';
+  const done = states.filter((s) => s === 'completed').length;
+  const allDone = states.every((s) => s === 'completed' || s === 'skipped');
+  return paint(`${done}/${inPlay} done`, allDone ? COLORS.gold : COLORS.dim, opts.color);
+}
+
+/** Render the full progress frame as one string (no trailing newline). */
+export function renderScan(input: RenderInput, opts: RenderOptions): string {
+  const byAgent = new Map(input.running.map((r) => [r.agent, r]));
+  const stateMap = deriveAgentStates(input);
+  const lines: string[] = ['', ...headerLines(input, opts), ''];
+
+  const metaFor = (name: string, state: RunState): string =>
+    agentMeta(state, input.state?.agentMetrics[name], byAgent.get(name), agentError(name, input.state, byAgent), opts);
+  // Only agents that have actually entered play are shown; pending/skipped ones stay hidden.
+  const inPlay = (s: RunState): boolean => s === 'running' || s === 'completed' || s === 'failed';
+
+  for (const phase of PIPELINE) {
+    const states = phase.agents.map((a) => stateMap.get(a.name) ?? 'pending');
+    const playing = states.filter(inPlay).length;
+    const phaseRunState: RunState = phaseGlyphState(states);
+
+    // A single-agent phase carries that agent's own duration/cost on the phase line once it
+    // starts; a parallel phase gets a "k/N done" summary over the agents in play.
+    const first = phase.agents[0];
+    const firstState = states[0];
+    const phaseMetaStr =
+      !phase.parallel && first && firstState && inPlay(firstState)
+        ? metaFor(first.name, firstState)
+        : phaseMeta(states, playing, phase.parallel, opts);
+    lines.push(`  ${glyph(phaseRunState, opts)}  ${phase.label.padEnd(26)}${phaseMetaStr}`);
+
+    if (!phase.parallel) continue;
+    for (let i = 0; i < phase.agents.length; i++) {
+      const agent = phase.agents[i];
+      const state = states[i];
+      if (!agent || !state || !inPlay(state)) continue;
+      lines.push(`       ${glyph(state, opts)} ${agent.label.padEnd(18)}${metaFor(agent.name, state)}`);
+    }
+  }
+
+  lines.push(...footerLines(input, opts));
+  return lines.join('\n');
+}
+
+function headerLines(input: RenderInput, opts: RenderOptions): string[] {
+  const elapsedMs = scanElapsedMs(input, opts.now);
+  const meta = [statusBadge(input, opts), elapsedMs !== undefined ? formatDuration(elapsedMs) : '—'].join(' · ');
+  return [`  ${paint('Scan:', COLORS.bold, opts.color)} ${input.workspace.padEnd(22)} ${meta}`];
+}
+
+/** Aligned label column for the footer's Logs / Temporal rows. */
+const FOOTER_LABEL_WIDTH = 12;
+
+/** A thin rule that sets the footer apart from the phase list above it. */
+function footerDivider(opts: RenderOptions): string {
+  return paint(`  ${(opts.unicode ? '─' : '-').repeat(60)}`, COLORS.dim, opts.color);
+}
+
+/** One footer row: an accent-colored label in a fixed column, then its value in the default color. */
+function footerRow(label: string, value: string, opts: RenderOptions): string {
+  return `  ${paint(label.padEnd(FOOTER_LABEL_WIDTH), COLORS.gold, opts.color)}${value}`;
+}
+
+function footerLines(input: RenderInput, opts: RenderOptions): string[] {
+  const prefix = commandPrefix();
+
+  if (isTerminal(input.temporalStatus) && input.state?.summary) {
+    const wall = formatDuration(input.state.summary.totalDurationMs);
+    return ['', `  Time Taken   ${wall}`];
+  }
+
+  const logsValue = `${prefix} logs ${input.workspace}`;
+  const temporalValue = temporalDashboardUrl(input.workflowId);
+
+  if (isTerminal(input.temporalStatus)) {
+    const reason = input.failureMessage ?? input.state?.error ?? 'no result recorded';
+    return [
+      footerDivider(opts),
+      paint(
+        `  ${input.temporalStatus === 'TERMINATED' ? 'Stopped' : 'Ended'} — ${truncate(reason, 240)}`,
+        COLORS.dim,
+        opts.color,
+      ),
+      footerRow('Logs', logsValue, opts),
+      footerRow('Temporal', temporalValue, opts),
+    ];
+  }
+
+  const lines = [footerDivider(opts), footerRow('Logs', logsValue, opts), footerRow('Temporal', temporalValue, opts)];
+  if (opts.live) lines.push('', paint('  Ctrl-C stops watching — the scan keeps running.', COLORS.dim, opts.color));
+  return lines;
+}

apps/cli/src/scan/status-json.ts

@@ -0,0 +1,68 @@
+/**
+ * Machine-readable snapshot of one scan, for `shannon status --json`.
+ *
+ * A point-in-time view built from the same derivation the human progress tree uses
+ * (derive.ts), so the JSON and the rendered tree can never disagree about an agent's
+ * state. One invocation is one snapshot — callers that want to track progress poll it.
+ */
+
+import type { DerivedPhase } from './derive.js';
+import { derivePipeline, isTerminal, scanElapsedMs } from './derive.js';
+import type { RenderInput } from './render.js';
+
+/** Coarse scan status token, mirroring the human status badge in machine-friendly form. */
+export type ScanStatus = 'running' | 'completed' | 'partial' | 'failed' | 'stopped' | 'cancelled' | 'timed_out';
+
+export interface StatusJson {
+  readonly workspace: string;
+  /** Temporal workflow id backing this scan (differs from workspace on a resume). */
+  readonly workflowId?: string;
+  /** Coarse outcome: `running` until the scan closes, then its terminal status. */
+  readonly status: ScanStatus;
+  /** Raw Temporal WorkflowExecutionStatusName, for callers that need the source status. */
+  readonly temporalStatus: string;
+  /** Wall-clock elapsed ms (live for a running scan, final for a closed one), or null when unknown. */
+  readonly elapsedMs: number | null;
+  readonly startedAt?: string;
+  readonly endedAt?: string;
+  /** Failure text when a failed scan left no readable state. */
+  readonly failureMessage?: string;
+  readonly phases: readonly DerivedPhase[];
+}
+
+/** Map the raw Temporal status (and workflow status) onto the coarse machine token. */
+function deriveStatus(input: RenderInput): ScanStatus {
+  if (!isTerminal(input.temporalStatus)) return 'running';
+  if (input.state?.status === 'partial') return 'partial';
+
+  switch (input.temporalStatus) {
+    case 'COMPLETED':
+      return 'completed';
+    case 'TERMINATED':
+      return 'stopped';
+    case 'CANCELLED':
+    case 'CANCELED':
+      return 'cancelled';
+    case 'TIMED_OUT':
+      return 'timed_out';
+    default:
+      return 'failed';
+  }
+}
+
+/** Build the JSON snapshot for a scan at instant `now`. */
+export function toStatusJson(input: RenderInput, now: number): StatusJson {
+  const elapsedMs = scanElapsedMs(input, now);
+
+  return {
+    workspace: input.workspace,
+    ...(input.workflowId !== undefined && { workflowId: input.workflowId }),
+    status: deriveStatus(input),
+    temporalStatus: input.temporalStatus,
+    elapsedMs: elapsedMs ?? null,
+    ...(input.startedAt !== undefined && { startedAt: new Date(input.startedAt).toISOString() }),
+    ...(input.endedAt !== undefined && { endedAt: new Date(input.endedAt).toISOString() }),
+    ...(input.failureMessage !== undefined && { failureMessage: input.failureMessage }),
+    phases: derivePipeline(input, now),
+  };
+}

apps/cli/src/session.ts

@@ -0,0 +1,26 @@
+/**
+ * Workspace → Temporal workflow-id resolution.
+ *
+ * A workspace name is not always its workflow id: a fresh scan's id equals the
+ * workspace name, but each resume spawns a new workflow (`<workspace>_resume_<ts>`).
+ * The workspace's session.json records the authoritative id — the latest resume
+ * attempt, or the original — so commands that query Temporal (status, stop) resolve
+ * through here instead of assuming the name is the id.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { getWorkspacesDir } from './home.js';
+import { resolveRunFile } from './paths.js';
+
+/** Latest workflow id recorded for a workspace: last resume attempt, else the original. */
+export function resolveWorkflowId(workspace: string): string | undefined {
+  const sessionPath = resolveRunFile(path.join(getWorkspacesDir(), workspace), 'session.json');
+  try {
+    const session = JSON.parse(fs.readFileSync(sessionPath, 'utf-8'));
+    const resumeAttempts: { workflowId?: string }[] = session.session?.resumeAttempts ?? [];
+    return resumeAttempts.at(-1)?.workflowId ?? session.session?.originalWorkflowId ?? undefined;
+  } catch {
+    return undefined;
+  }
+}

apps/cli/src/splash.ts

@@ -5,50 +5,73 @@
 
 import { supportsColor } from './tty.js';
 
+/** SHANNON wordmark. Block glyphs take the row fill; box-drawing strokes take the deeper edge shade. */
+const SHANNON = [
+  '███████╗██╗  ██╗ █████╗ ███╗   ██╗███╗   ██╗ ██████╗ ███╗   ██╗',
+  '██╔════╝██║  ██║██╔══██╗████╗  ██║████╗  ██║██╔═══██╗████╗  ██║',
+  '███████╗███████║███████║██╔██╗ ██║██╔██╗ ██║██║   ██║██╔██╗ ██║',
+  '╚════██║██╔══██║██╔══██║██║╚██╗██║██║╚██╗██║██║   ██║██║╚██╗██║',
+  '███████║██║  ██║██║  ██║██║ ╚████║██║ ╚████║╚██████╔╝██║ ╚████║',
+  '╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═══╝',
+];
+
+/**
+ * Sunset ramp, yellow at the top row down to burnt orange at the base.
+ * Wordmark row i is filled with stop i and edged with stop i + 1, so the
+ * box-drawing strokes read as a shadow one shade deeper than their row.
+ * `xterm` is the 256-color approximation for terminals without 24-bit color.
+ */
+const SUNSET: ReadonlyArray<{ rgb: readonly [number, number, number]; xterm: number }> = [
+  { rgb: [247, 203, 45], xterm: 220 },
+  { rgb: [246, 182, 38], xterm: 220 },
+  { rgb: [245, 160, 32], xterm: 214 },
+  { rgb: [242, 141, 28], xterm: 214 },
+  { rgb: [238, 121, 24], xterm: 208 },
+  { rgb: [231, 100, 21], xterm: 208 },
+  { rgb: [222, 82, 19], xterm: 202 },
+];
+
 export function displaySplash(version?: string): void {
   const color = supportsColor();
-  const GOLD = color ? '\x1b[38;2;244;197;66m' : '';
-  const CYAN = color ? '\x1b[36;1m' : '';
-  const WHITE = color ? '\x1b[1;37m' : '';
-  const GRAY = color ? '\x1b[0;37m' : '';
-  const YELLOW = color ? '\x1b[1;33m' : '';
+  const truecolor = color && /truecolor|24bit/i.test(process.env.COLORTERM ?? '');
   const RESET = color ? '\x1b[0m' : '';
+  const WHITE = color ? '\x1b[1;97m' : '';
+  const GRAY = color ? '\x1b[0;37m' : '';
+  const DIM = color ? '\x1b[90m' : '';
 
-  const B = `${CYAN}\u2551${RESET}`;
-  const S67 = ' '.repeat(67);
-  const HR = '\u2550'.repeat(67);
+  const ramp = SUNSET.map(({ rgb: [r, g, b], xterm }) => {
+    if (!color) return '';
+    return truecolor ? `\x1b[38;2;${r};${g};${b}m` : `\x1b[38;5;${xterm}m`;
+  });
+
+  /** Color one wordmark row, emitting an escape only where the run changes. Spaces stay unpainted. */
+  const paint = (row: string, fill: string, edge: string): string => {
+    if (!color) return row;
+    let out = '';
+    let open = '';
+    for (const ch of row) {
+      const want = ch === ' ' ? '' : ch === '█' ? fill : edge;
+      if (want !== open) {
+        if (open) out += RESET;
+        out += want;
+        open = want;
+      }
+      out += ch;
+    }
+    return open ? out + RESET : out;
+  };
 
   const lines = [
     '',
-    `  ${CYAN}\u2554${HR}\u2557${RESET}`,
-    `  ${B}${S67}${B}`,
-    `  ${B}  ${GOLD}\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2557  \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557   \u2588\u2588\u2557\u2588\u2588\u2588\u2557   \u2588\u2588\u2557 \u2588\u2588\u2588\u2588\u2588\u2588\u2557 \u2588\u2588\u2588\u2557   \u2588\u2588\u2557${RESET}  ${B}`,
-    `  ${B}  ${GOLD}\u2588\u2588\u2554\u2550\u2550\u2550\u2550\u255D\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2550\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2557  \u2588\u2588\u2551${RESET}  ${B}`,
-    `  ${B}  ${GOLD}\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2557\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2554\u2588\u2588\u2557 \u2588\u2588\u2551${RESET}  ${B}`,
-    `  ${B}  ${GOLD}\u255A\u2550\u2550\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2554\u2550\u2550\u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551\u2588\u2588\u2551   \u2588\u2588\u2551\u2588\u2588\u2551\u255A\u2588\u2588\u2557\u2588\u2588\u2551${RESET}  ${B}`,
-    `  ${B}  ${GOLD}\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551  \u2588\u2588\u2551\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551\u255A\u2588\u2588\u2588\u2588\u2588\u2588\u2554\u255D\u2588\u2588\u2551 \u255A\u2588\u2588\u2588\u2588\u2551${RESET}  ${B}`,
-    `  ${B}  ${GOLD}\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D\u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D \u255A\u2550\u2550\u2550\u2550\u2550\u255D \u255A\u2550\u255D  \u255A\u2550\u2550\u2550\u255D${RESET}  ${B}`,
-    `  ${B}${S67}${B}`,
-    `  ${B}              ${CYAN}\u2554\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2557${RESET}               ${B}`,
-    `  ${B}              ${CYAN}\u2551${RESET}  ${WHITE}AI Penetration Testing Framework${RESET}  ${CYAN}\u2551${RESET}               ${B}`,
-    `  ${B}              ${CYAN}\u255A\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u255D${RESET}               ${B}`,
-    `  ${B}${S67}${B}`,
-  ];
-
-  if (version) {
-    const verStr = `v${version}`;
-    const verPadLeft = Math.floor((67 - verStr.length) / 2);
-    const verPadRight = 67 - verStr.length - verPadLeft;
-    lines.push(`  ${B}${' '.repeat(verPadLeft)}${GRAY}${verStr}${RESET}${' '.repeat(verPadRight)}${B}`);
-  }
-
-  lines.push(
-    `  ${B}${S67}${B}`,
-    `  ${B}                    ${YELLOW}\uD83D\uDD10 DEFENSIVE SECURITY ONLY \uD83D\uDD10${RESET}                  ${B}`,
-    `  ${B}${S67}${B}`,
-    `  ${CYAN}\u255A${HR}\u255D${RESET}`,
+    `  ${WHITE}Keygraph${RESET}${version ? `  ${DIM}v${version}${RESET}` : ''}`,
     '',
-  );
+    ...SHANNON.map((row, i) => `  ${paint(row, ramp[i] ?? '', ramp[i + 1] ?? '')}`),
+    '',
+    `  ${WHITE}AI Pentester for Web Apps and APIs${RESET}`,
+    '',
+    `  ${GRAY}-Authorized Security Testing Only-${RESET}`,
+    '',
+  ];
 
   console.log(lines.join('\n'));
 }

apps/cli/src/suggest.ts

@@ -0,0 +1,58 @@
+/**
+ * "Did you mean?" suggestions for mistyped commands and flags.
+ *
+ * A single Levenshtein-based matcher powers both the unknown-command path in the
+ * dispatcher and the unknown-option path in `parseArgs`, so a typo like `statsu`
+ * or `--workspce` points the user at the closest real name instead of just failing.
+ */
+
+/** Levenshtein edit distance between two strings (insertions, deletions, substitutions). */
+export function editDistance(a: string, b: string): number {
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+
+  // Rolling single row; `diagonal` and `above` carry the two neighbours a full grid would.
+  const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+
+  for (let i = 1; i <= a.length; i++) {
+    let diagonal = row[0] as number;
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const above = row[j] as number;
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      row[j] = Math.min(above + 1, (row[j - 1] as number) + 1, diagonal + cost);
+      diagonal = above;
+    }
+  }
+  return row[b.length] as number;
+}
+
+/**
+ * The candidate closest to `input`, or undefined if none is near enough.
+ *
+ * A prefix match ("stat" -> "status") wins first; otherwise the lowest edit
+ * distance within a length-scaled threshold, so unrelated words don't match.
+ */
+export function closestMatch(input: string, candidates: readonly string[]): string | undefined {
+  if (input.length >= 2) {
+    const prefix = candidates.find((candidate) => candidate.startsWith(input));
+    if (prefix) return prefix;
+  }
+
+  let best: string | undefined;
+  let bestDistance = Number.POSITIVE_INFINITY;
+  for (const candidate of candidates) {
+    if (candidate.length <= 3) continue;
+
+    const distance = editDistance(input, candidate);
+    if (distance < bestDistance) {
+      bestDistance = distance;
+      best = candidate;
+    }
+  }
+
+  if (best === undefined) return undefined;
+
+  const threshold = Math.max(2, Math.floor(best.length / 3));
+  return bestDistance <= threshold ? best : undefined;
+}

apps/cli/src/temporal-client.ts

@@ -0,0 +1,126 @@
+/**
+ * Thin Temporal client for reading one scan's state.
+ *
+ * A running scan is queried live (getProgress) and read via pendingActivities for
+ * the in-flight agents; a closed scan is read once from its result. Everything goes
+ * straight to the frontend on 127.0.0.1:7233 — the gRPC port the compose file
+ * publishes — so this needs Temporal up, but no worker of its own.
+ */
+
+import { Client, Connection, WorkflowFailedError, WorkflowNotFoundError } from '@temporalio/client';
+import { ACTIVITY_TO_AGENT, type PipelineState } from './scan/pipeline.js';
+
+const ADDRESS = '127.0.0.1:7233';
+const NAMESPACE = 'default';
+
+export interface RunningAgent {
+  readonly agent: string;
+  readonly attempt: number;
+  readonly startedAt?: number;
+  readonly lastFailure?: string;
+}
+
+/** Convert a proto ITimestamp (seconds is a Long) to epoch millis. */
+function timestampMs(
+  ts: { seconds?: { toString(): string } | number | null; nanos?: number | null } | null,
+): number | undefined {
+  const seconds = ts?.seconds;
+  if (seconds == null) return undefined;
+  const secNum = typeof seconds === 'number' ? seconds : Number(seconds.toString());
+  return secNum * 1000 + (ts?.nanos ?? 0) / 1e6;
+}
+
+export interface ScanDescription {
+  /** WorkflowExecutionStatusName: RUNNING | COMPLETED | FAILED | CANCELLED | TERMINATED | TIMED_OUT | … */
+  readonly status: string;
+  readonly startedAt?: number;
+  readonly closedAt?: number;
+  readonly runningAgents: readonly RunningAgent[];
+}
+
+export type TerminalOutcome =
+  | { readonly kind: 'success'; readonly state: PipelineState }
+  | { readonly kind: 'failed'; readonly message: string };
+
+let clientPromise: Promise<Client> | null = null;
+
+function getClient(): Promise<Client> {
+  if (!clientPromise) {
+    clientPromise = Connection.connect({ address: ADDRESS }).then(
+      (connection) => new Client({ connection, namespace: NAMESPACE }),
+    );
+  }
+  return clientPromise;
+}
+
+/** Describe a scan: status, timing, and the agents currently running (from pendingActivities). Null if not found. */
+export async function describeScan(workflowId: string): Promise<ScanDescription | null> {
+  const client = await getClient();
+  try {
+    const desc = await client.workflow.getHandle(workflowId).describe();
+
+    const runningAgents: RunningAgent[] = [];
+    for (const pending of desc.raw.pendingActivities ?? []) {
+      const agent = ACTIVITY_TO_AGENT[pending.activityType?.name ?? ''];
+      if (!agent) continue;
+      const lastFailure = pending.lastFailure?.message;
+      const startedAt = timestampMs(pending.scheduledTime ?? pending.lastStartedTime ?? null);
+      runningAgents.push({
+        agent,
+        attempt: pending.attempt ?? 1,
+        ...(startedAt !== undefined ? { startedAt } : {}),
+        ...(lastFailure ? { lastFailure } : {}),
+      });
+    }
+
+    return {
+      status: desc.status.name,
+      runningAgents,
+      ...(desc.startTime ? { startedAt: desc.startTime.getTime() } : {}),
+      ...(desc.closeTime ? { closedAt: desc.closeTime.getTime() } : {}),
+    };
+  } catch (err) {
+    if (err instanceof WorkflowNotFoundError) return null;
+    throw err;
+  }
+}
+
+/** Live progress of a running scan via the getProgress query. Null if the query can't be served (no worker). */
+export async function queryProgress(workflowId: string): Promise<PipelineState | null> {
+  const client = await getClient();
+  try {
+    return await client.workflow.getHandle(workflowId).query<PipelineState>('getProgress');
+  } catch {
+    // The query needs a live worker; a just-closed scan may have none. Caller falls back to the result.
+    return null;
+  }
+}
+
+/**
+ * Deepest message in a Temporal failure's cause chain — the real reason nested under generic
+ * wrappers (WorkflowFailedError → ActivityFailure → ApplicationFailure). Covers failed, cancelled,
+ * and terminated alike. Mirrors the SDK's `rootCause` (only exported from @temporalio/common).
+ */
+function rootFailureMessage(err: WorkflowFailedError): string {
+  let message = err.message;
+  let cause: unknown = err.cause;
+  while (cause instanceof Error && cause.message) {
+    message = cause.message;
+    cause = cause.cause;
+  }
+  return message;
+}
+
+/** Final state of a closed scan: success carries the full PipelineState, failure carries the message. */
+export async function getTerminalOutcome(workflowId: string): Promise<TerminalOutcome> {
+  const client = await getClient();
+  try {
+    const state = (await client.workflow.getHandle(workflowId).result()) as PipelineState;
+    return { kind: 'success', state };
+  } catch (err) {
+    if (err instanceof WorkflowFailedError) {
+      return { kind: 'failed', message: rootFailureMessage(err) };
+    }
+    throw err;
+  }
+}

apps/cli/src/tty.ts

@@ -3,6 +3,8 @@
  * whether the user can be prompted interactively.
  */
 
+import { fail } from './errors.js';
+
 /** True when stdout is a real terminal — safe for color, cursor moves, and spinners. */
 export function stdoutIsTerminal(): boolean {
   return !!process.stdout.isTTY;
@@ -28,7 +30,5 @@ export function supportsColor(): boolean {
 /** Exit with a clear error when an interactive-only command has no terminal, instead of hanging on a prompt. */
 export function requireInteractive(command: string, alternative: string): void {
   if (isInteractive()) return;
-  console.error(`ERROR: '${command}' needs an interactive terminal.`);
-  console.error(alternative);
-  process.exit(1);
+  fail(`'${command}' needs an interactive terminal.`, alternative);
 }

apps/cli/src/ui.ts

@@ -0,0 +1,60 @@
+/**
+ * Terminal status output for long-running steps.
+ *
+ * Commands are run with their output captured rather than inherited, so raw docker
+ * plumbing never floods the terminal. Progress is shown with a `@clack/prompts`
+ * spinner. On failure the captured output is printed so the error stays visible
+ * instead of being swallowed.
+ */
+
+import { spawn } from 'node:child_process';
+import * as p from '@clack/prompts';
+
+export interface StepResult {
+  ok: boolean;
+  output: string;
+}
+
+/**
+ * Run a command capturing stdout and stderr. Resolves the exit result and combined
+ * output; never rejects. Callers that want a spinner wrap this in one themselves.
+ */
+export function spawnCaptured(cmd: string, args: string[]): Promise<StepResult> {
+  return new Promise((resolve) => {
+    let output = '';
+    const child = spawn(cmd, args, { stdio: ['ignore', 'pipe', 'pipe'] });
+    child.stdout?.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.stderr?.on('data', (chunk) => {
+      output += chunk.toString();
+    });
+    child.on('close', (code) => resolve({ ok: code === 0, output }));
+    child.on('error', () => resolve({ ok: false, output }));
+  });
+}
+
+/** Print captured command output to stderr, so a failure is never swallowed. */
+export function surfaceOutput(output: string): void {
+  const trimmed = output.trim();
+  if (trimmed) process.stderr.write(`${trimmed}\n`);
+}
+
+/**
+ * Run a command as a labeled step, with a spinner over it. On failure the captured
+ * output is surfaced. Returns the exit result and captured output.
+ */
+export async function runStep(label: string, cmd: string, args: string[]): Promise<StepResult> {
+  const spinner = p.spinner();
+  spinner.start(label);
+
+  const result = await spawnCaptured(cmd, args);
+  if (result.ok) {
+    spinner.stop(label);
+  } else {
+    spinner.error(label);
+    surfaceOutput(result.output);
+  }
+
+  return result;
+}

apps/worker/configs/config-schema.json

@@ -206,7 +206,6 @@
       "properties": {
         "description": {
           "type": "string",
-          "minLength": 1,
           "maxLength": 200,
           "description": "Human-readable description of the rule"
         },
@@ -222,7 +221,7 @@
           "description": "Value to match"
         }
       },
-      "required": ["description", "type", "value"],
+      "required": ["type", "value"],
       "additionalProperties": false
     }
   }

apps/worker/prompts/report-executive.txt

@@ -89,7 +89,7 @@ Fields:
 - `executive_summary`: 2-3 sentences summarizing the security posture for technical leadership (CTOs, CISOs, Engineering VPs). Must include the target URL and assessment date. Provide a high-level characterization based on the findings — severity distribution, most critical issues, and overall risk demonstrated by exploitation. If no vulnerabilities were confirmed in the assessed classes, state that scope clearly. A clean report is valid only when no <not_assessed_classes> block is present. If that block is present, explicitly say the listed classes were not assessed and do not assert they are free of vulnerabilities.
 </exploit_mode_summary>
 <analysis_mode_summary>
-- `executive_summary`: 2-3 sentences summarizing the security posture for technical leadership (CTOs, CISOs, Engineering VPs). Must include the target URL and assessment date. Provide a high-level characterization based on the findings — confidence distribution, the most serious weaknesses identified, and overall risk. State plainly that this was an analysis-only assessment and that no finding was confirmed by exploitation; do not describe risk as demonstrated or proven. Findings carry no severity rating in this mode, so do not assert one. If no vulnerabilities were identified in the assessed classes, state that scope clearly. A clean report is valid only when no <not_assessed_classes> block is present. If that block is present, explicitly say the listed classes were not assessed and do not assert they are free of vulnerabilities.
+- `executive_summary`: 2-3 sentences summarizing the security posture for technical leadership (CTOs, CISOs, Engineering VPs). Must include the target URL and assessment date. Provide a high-level characterization based on the findings — severity and confidence distribution, the most serious weaknesses identified, and overall risk. State plainly that this was an analysis-only assessment and that no finding was confirmed by exploitation; do not describe risk as demonstrated or proven, and present severity as assessed rather than measured. If no vulnerabilities were identified in the assessed classes, state that scope clearly. A clean report is valid only when no <not_assessed_classes> block is present. If that block is present, explicitly say the listed classes were not assessed and do not assert they are free of vulnerabilities.
 </analysis_mode_summary>
 </record_report_meta>
 
@@ -112,6 +112,7 @@ Map the finding's content from the per-class deliverable sections to `add_findin
 </exploit_mode_fields>
 <analysis_mode_fields>
 - `confidence`: From the finding's "Confidence" field. Use as-is; do not reassess.
+- `severity`: The analysis deliverables carry no severity field — no exploit ran to measure impact. Assess it from the vulnerability class and the impact you describe. It is an assessed rating, not a measured one.
 </analysis_mode_fields>
 - `owasp_category`: Map to the appropriate OWASP Top 10 (2025) category:
   - `"A01:2025 — Broken Access Control"`
@@ -139,7 +140,7 @@ Map the finding's content from the per-class deliverable sections to `add_findin
 <analysis_mode_fields>
 - `impact`: What an attacker could achieve if this vulnerability were exploited. Derive it from the finding's "Impact" and "Overview" fields. Write it as assessed, never as achieved.
 
-This run had no exploitation phase. Nothing was executed against the target, nothing was demonstrated, and no exploit evidence exists. Accordingly `severity`, `auth_state`, `prerequisites`, `exploitation_steps`, `proof_of_impact` and `status` are **not** part of your tool schema — the deliverables contain no source for any of them. `confidence` is the only rating this run produces; take it straight from the deliverable. Do not compensate for the missing fields by describing attack execution in `overview`, `impact` or `notes`. Report the weakness and how to fix it; that is the whole deliverable for this run.
+This run had no exploitation phase. Nothing was executed against the target, nothing was demonstrated, and no exploit evidence exists. Accordingly `auth_state`, `prerequisites`, `exploitation_steps`, `proof_of_impact` and `status` are **not** part of your tool schema — the deliverables contain no source for any of them. `confidence` is the deliverable's own rating and carries over verbatim; `severity` is yours to assess, since nothing measured it. Do not compensate for the missing fields by describing attack execution in `overview`, `impact` or `notes`. Report the weakness and how to fix it; that is the whole deliverable for this run.
 </analysis_mode_fields>
 
 **Optional fields:**
@@ -160,6 +161,7 @@ If no valid findings exist after filtering, do not call `add_finding` at all. Th
 - **No Fabrications:** Every piece of data must come from the deliverable files. If a finding has incomplete data, include it but note the gap in `overview`.
 - **Nothing Was Demonstrated:** No exploit ran. Do not write that a vulnerability was confirmed, proven, exploited, or verified against the running target, and do not describe payloads, requests, or responses as having been sent.
 - **No Confidence Changes:** Use the confidence from the deliverable as-is. Do not raise or lower it.
+- **Severity Is Assessed:** Rate severity from the vulnerability class and the impact you describe. Never present it as measured or demonstrated.
 </analysis_mode_constraints>
 - **No Speculation:** Only record findings that appear in the deliverables with valid vulnerability IDs. Do not add your own assessments.
 - **OWASP 2025:** Map all findings to OWASP Top 10 (2025) categories.
@@ -187,6 +189,7 @@ Before finalizing, verify:
 </exploit_mode_checks>
 <analysis_mode_checks>
 - [ ] Does every finding have `confidence` carried over unchanged from the deliverable?
+- [ ] Is every `severity` assessed from the impact I described, with no claim that it was measured?
 - [ ] Is every `impact` phrased as assessed rather than demonstrated, with no claim that anything was executed?
 </analysis_mode_checks>
 - [ ] Are remediation recommendations specific and actionable (not generic)?

apps/worker/src/ai/models.ts

@@ -21,21 +21,34 @@
  * built over an in-memory credential store primed from the environment.
  */
 
+import { existsSync } from 'node:fs';
+import path from 'node:path';
 import type { Api, Credential, CredentialInfo, CredentialStore, Model } from '@earendil-works/pi-ai';
-import { ModelRuntime } from '@earendil-works/pi-coding-agent';
-
-/** Providers Shannon can currently reach. Each is a pi-ai provider id. */
-export const SUPPORTED_PROVIDERS = ['anthropic', 'openai', 'xai', 'amazon-bedrock'] as const;
-
-export type ProviderId = (typeof SUPPORTED_PROVIDERS)[number];
+import { getAgentDir, ModelRuntime } from '@earendil-works/pi-coding-agent';
 
 /**
- * Env vars carrying each provider's API key, in precedence order. Shannon does not
- * invent credential names — these are the variables each provider's own tooling
- * uses. Bedrock pairs its bearer token with AWS_REGION, which is provider config
- * rather than a credential.
+ * Providers Shannon curates with their own credential variables, config sections,
+ * and setup flows. Each is a pi-ai provider id; any other pi provider is still
+ * reachable through the generic credential path below.
  */
-export const PROVIDER_API_KEY_ENV: Readonly<Record<ProviderId, readonly string[]>> = {
+export const CURATED_PROVIDERS = ['anthropic', 'openai', 'xai', 'amazon-bedrock'] as const;
+
+export type CuratedProviderId = (typeof CURATED_PROVIDERS)[number];
+
+function isCuratedProvider(value: string): value is CuratedProviderId {
+  return (CURATED_PROVIDERS as readonly string[]).includes(value);
+}
+
+/** Generic API key, honored for any provider Shannon does not curate. */
+export const GENERIC_API_KEY_ENV = 'SHANNON_AI_API_KEY';
+
+/**
+ * Env vars carrying each curated provider's API key, in precedence order. Shannon
+ * does not invent credential names — these are the variables each provider's own
+ * tooling uses. Bedrock pairs its bearer token with AWS_REGION, which is provider
+ * config rather than a credential.
+ */
+export const PROVIDER_API_KEY_ENV: Readonly<Record<CuratedProviderId, readonly string[]>> = {
   anthropic: ['ANTHROPIC_API_KEY', 'CLAUDE_CODE_OAUTH_TOKEN'],
   openai: ['OPENAI_API_KEY'],
   xai: ['XAI_API_KEY'],
@@ -45,6 +58,9 @@ export const PROVIDER_API_KEY_ENV: Readonly<Record<ProviderId, readonly string[]
 /** Model used when SHANNON_AI_MODEL is unset. */
 export const DEFAULT_MODEL_SPEC = 'anthropic:claude-sonnet-4-6';
 
+/** Browsable pi model catalogue — the source of valid `<provider>:<model-id>` ids. */
+export const PI_CATALOG_URL = 'https://pi.dev/models';
+
 /**
  * Wire formats an OpenAI-compatible gateway may serve, named by
  * SHANNON_AI_OPENAI_FORMAT. Only `openai` offers a choice: every other supported
@@ -82,18 +98,14 @@ export function resolveOpenAiFormat(): OpenAiFormat | undefined {
 }
 
 export interface ModelSpec {
-  providerId: ProviderId;
+  providerId: string;
   modelId: string;
 }
 
-function isSupportedProvider(value: string): value is ProviderId {
-  return (SUPPORTED_PROVIDERS as readonly string[]).includes(value);
-}
-
 /**
- * Parse a `<provider>:<model-id>` spec. Splits on the first colon only, so
- * colons inside a model ID survive. Throws with the supported provider list on
- * a malformed or unknown provider.
+ * Parse a `<provider>:<model-id>` spec. Splits on the first colon only, so colons
+ * inside a model ID survive. The provider id is passed through as given — pi's
+ * registry validates it later — so this throws only on a malformed spec.
  */
 export function parseModelSpec(spec: string): ModelSpec {
   const trimmed = spec.trim();
@@ -112,11 +124,6 @@ export function parseModelSpec(spec: string): ModelSpec {
       `SHANNON_AI_MODEL must be "<provider>:<model-id>", got "${trimmed}". Example: ${DEFAULT_MODEL_SPEC}`,
     );
   }
-  if (!isSupportedProvider(providerId)) {
-    throw new Error(
-      `Unsupported provider "${providerId}" in SHANNON_AI_MODEL. Supported providers: ${SUPPORTED_PROVIDERS.join(', ')}`,
-    );
-  }
 
   return { providerId, modelId };
 }
@@ -133,17 +140,25 @@ export interface ProviderCredentials {
   apiKey?: string;
 }
 
-/** Collect the API key and optional endpoint override for a provider. */
-export function resolveProviderCredentials(providerId: ProviderId): ProviderCredentials {
+/**
+ * Collect the API key and optional endpoint override for a provider. A curated
+ * provider's own variables win, then the generic SHANNON_AI_API_KEY. Bedrock is
+ * excluded — it authenticates through its AWS_ variables, which pi reads directly.
+ */
+export function resolveProviderCredentials(providerId: string): ProviderCredentials {
   const credentials: ProviderCredentials = {};
 
-  for (const name of PROVIDER_API_KEY_ENV[providerId]) {
+  const namedVars = isCuratedProvider(providerId) ? PROVIDER_API_KEY_ENV[providerId] : [];
+  for (const name of namedVars) {
     const value = process.env[name];
     if (value) {
       credentials.apiKey = value;
       break;
     }
   }
+  if (!credentials.apiKey && providerId !== 'amazon-bedrock' && process.env[GENERIC_API_KEY_ENV]) {
+    credentials.apiKey = process.env[GENERIC_API_KEY_ENV];
+  }
   if (process.env.SHANNON_AI_BASE_URL) credentials.baseUrl = process.env.SHANNON_AI_BASE_URL;
 
   return credentials;
@@ -190,12 +205,29 @@ class RuntimeCredentialStore implements CredentialStore {
   }
 }
 
+/** The file pi reads credentials from: the agent dir's auth.json. */
+function piAuthPath(): string {
+  return path.join(getAgentDir(), 'auth.json');
+}
+
+/** Whether the host's pi credentials are mounted (auth.json present in the agent dir). */
+export function piAuthPresent(): boolean {
+  return existsSync(piAuthPath());
+}
+
 /**
  * Build a ModelRuntime whose only credential is the one supplied. Model catalogs
  * stay offline (`allowModelNetwork` defaults to false) so a scan never blocks on
  * a catalog refresh.
+ *
+ * When the host's pi auth.json is present, the runtime reads it instead: pi's
+ * disk-backed store resolves the credential. The mount is writable so OAuth
+ * refreshes persist to the host for subsequent runs.
  */
 export async function createModelRuntime(providerId: string, apiKey: string | undefined): Promise<ModelRuntime> {
+  if (piAuthPresent()) {
+    return ModelRuntime.create({ authPath: piAuthPath() });
+  }
   return ModelRuntime.create({ credentials: new RuntimeCredentialStore(providerId, apiKey) });
 }
 
@@ -203,7 +235,7 @@ export interface ModelSelection {
   model: Model<Api>;
   modelRuntime: ModelRuntime;
   modelId: string;
-  providerId: ProviderId;
+  providerId: string;
 }
 
 /**
@@ -218,7 +250,7 @@ export interface ModelSelection {
  * then describes the format in use. Every other provider has one API and only
  * changes address.
  */
-function pointAtGateway(model: Model<Api>, providerId: ProviderId, baseUrl: string, format: OpenAiFormat): Model<Api> {
+function pointAtGateway(model: Model<Api>, providerId: string, baseUrl: string, format: OpenAiFormat): Model<Api> {
   if (providerId !== 'openai') return { ...model, baseUrl };
   if (format === 'responses') return { ...model, baseUrl, api: OPENAI_FORMATS.responses };
 
@@ -240,7 +272,7 @@ function pointAtGateway(model: Model<Api>, providerId: ProviderId, baseUrl: stri
  */
 export function resolveModel(
   modelRuntime: ModelRuntime,
-  providerId: ProviderId,
+  providerId: string,
   modelId: string,
   baseUrl: string | undefined,
   format: OpenAiFormat = DEFAULT_OPENAI_FORMAT,
@@ -265,7 +297,7 @@ export function resolveModel(
  * are configured, so it is rejected outside that combination rather than
  * silently ignored.
  */
-export function resolveGatewayFormat(providerId: ProviderId, baseUrl: string | undefined): OpenAiFormat {
+export function resolveGatewayFormat(providerId: string, baseUrl: string | undefined): OpenAiFormat {
   const configured = resolveOpenAiFormat();
   if (!configured) return DEFAULT_OPENAI_FORMAT;
 
@@ -296,7 +328,9 @@ export async function resolveModelSelection(): Promise<ModelSelection> {
 
   const model = resolveModel(modelRuntime, providerId, modelId, credentials.baseUrl, format);
   if (!model) {
-    throw new Error(`Model not found in pi registry: provider="${providerId}" model="${modelId}"`);
+    throw new Error(
+      `Model not found in pi registry: provider="${providerId}" model="${modelId}". Browse valid providers and models at ${PI_CATALOG_URL}.`,
+    );
   }
 
   return {

apps/worker/src/ai/pi/pi-executor.ts

@@ -290,6 +290,14 @@ export async function runPiPrompt(
   // Declared out here so the catch can bill spend accrued before a failure.
   let session: AgentSession | undefined;
 
+  // Abort the in-flight agent when the Temporal activity is cancelled (UI/CLI cancel).
+  // Without this the top-level session runs to startToCloseTimeout despite the cancel.
+  const onCancellation = (): void => {
+    void session?.abort().catch(() => {
+      // Best-effort — the session is torn down regardless once the prompt unwinds.
+    });
+  };
+
   progress.start();
 
   try {
@@ -307,6 +315,13 @@ export async function runPiPrompt(
       resourceLoader,
     }));
 
+    // Wire activity cancellation to the session now that it exists.
+    if (cancellationSignal?.aborted) {
+      onCancellation();
+    } else {
+      cancellationSignal?.addEventListener('abort', onCancellation, { once: true });
+    }
+
     // 5. Map pi events to audit logging + progress + error capture.
     session.subscribe((event: AgentSessionEvent) => {
       switch (event.type) {
@@ -414,5 +429,7 @@ export async function runPiPrompt(
       cacheWriteTokens: usage.cacheWriteTokens,
       retryable: isRetryableFailure(err),
     };
+  } finally {
+    cancellationSignal?.removeEventListener('abort', onCancellation);
   }
 }

apps/worker/src/collectors/finding-collector.ts

@@ -37,7 +37,7 @@ const OWASP_CATEGORY_VALUES = [
   'A10:2025 — Mishandling of Exceptional Conditions',
 ] as const;
 
-const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low', 'informational'] as const;
+const SEVERITY_VALUES = ['critical', 'high', 'medium', 'low'] as const;
 const STATUS_VALUES = ['exploited', 'out_of_scope', 'blocked_by_constraints', 'false_positive'] as const;
 const CONFIDENCE_VALUES = ['high', 'medium', 'low'] as const;
 
@@ -117,8 +117,18 @@ const AdditionalSectionSchema = Type.Object({
   }),
 });
 
-function identityFields() {
+/**
+ * `severity` is recorded in both modes, but it does not mean the same thing in each: an exploit
+ * run measures it from what the exploit demonstrated, an analysis run assesses it from the class
+ * of flaw. The description says which, so the agent never presents an assessment as a measurement.
+ */
+function identityFields(exploit: boolean) {
+  const severityDescription = exploit
+    ? 'Severity of the finding, based on the impact the exploit demonstrated.'
+    : 'Severity of the finding, assessed from the vulnerability class and the impact it would have.';
+
   return {
+    severity: stringEnum(SEVERITY_VALUES, { description: severityDescription }),
     finding_id: Type.String({
       minLength: 1,
       description: 'Finding identifier (e.g., "AUTH-VULN-07", "INJ-VULN-03"). Must be unique per report.',
@@ -178,9 +188,6 @@ function narrativeFields(exploit: boolean) {
 /** Fields that only mean something once an exploit has run. Absent from the analysis schema. */
 function exploitOnlyFields() {
   return {
-    severity: stringEnum(SEVERITY_VALUES, {
-      description: 'Severity of the finding, based on the impact the exploit demonstrated.',
-    }),
     auth_state: Type.String({
       minLength: 1,
       description: 'Authentication state during testing (e.g., "Unauthenticated", "Any authenticated user").',
@@ -205,7 +212,7 @@ function exploitOnlyFields() {
   };
 }
 
-/** Replaces `severity` when nothing was exploited. */
+/** Accompanies `severity` when nothing was exploited — the rating the analysis deliverable itself carries. */
 function analysisOnlyFields() {
   return {
     confidence: stringEnum(CONFIDENCE_VALUES, {
@@ -233,7 +240,7 @@ function sharedOptionalFields() {
 
 export function buildAddFindingSchema(exploit: boolean) {
   return Type.Object({
-    ...identityFields(),
+    ...identityFields(exploit),
     ...(exploit ? exploitOnlyFields() : analysisOnlyFields()),
     ...locationFields(),
     ...narrativeFields(exploit),
@@ -243,12 +250,12 @@ export function buildAddFindingSchema(exploit: boolean) {
 
 /**
  * Superset of both modes, for typing only. Consumers must check presence rather than assume:
- * `report.json` from an analysis run has no `severity` or `exploitation_steps` key at all.
+ * `report.json` from an analysis run has no `exploitation_steps` key at all. `severity` is the
+ * exception — both modes record it, so it is required here too.
  */
 const AddFindingSupersetSchema = Type.Object({
-  ...identityFields(),
+  ...identityFields(true),
   code_locations: Type.Optional(Type.Array(CodeLocationSchema)),
-  severity: Type.Optional(stringEnum(SEVERITY_VALUES)),
   auth_state: Type.Optional(Type.String()),
   prerequisites: Type.Optional(Type.String()),
   exploitation_steps: Type.Optional(Type.Array(StructuredStepSchema)),

apps/worker/src/config-parser.ts

@@ -514,7 +514,7 @@ const validateRulesSecurity = (rules: Rule[] | undefined, ruleType: string): voi
           ErrorCode.CONFIG_VALIDATION_FAILED,
         );
       }
-      if (pattern.test(rule.description)) {
+      if (rule.description !== undefined && pattern.test(rule.description)) {
         throw new PentestError(
           `rules.${ruleType}[${index}].description contains potentially dangerous pattern: ${pattern.source}`,
           'config',
@@ -656,11 +656,15 @@ const checkForConflicts = (avoidRules: Rule[] = [], focusRules: Rule[] = []): vo
 };
 
 const sanitizeRule = (rule: Rule): Rule => {
-  return {
-    description: rule.description.trim(),
+  const sanitized: Rule = {
     type: rule.type.toLowerCase().trim() as Rule['type'],
     value: rule.value.trim(),
   };
+  const description = rule.description?.trim();
+  if (description) {
+    sanitized.description = description;
+  }
+  return sanitized;
 };
 
 export const distributeConfig = (config: Config | null): DistributedConfig => {
@@ -702,13 +706,15 @@ const sanitizeAuthentication = (auth: Authentication): Authentication => {
     credentials: {
       username: auth.credentials.username.trim(),
       ...(auth.credentials.password && { password: auth.credentials.password }),
-      ...(auth.credentials.totp_secret && { totp_secret: auth.credentials.totp_secret.trim() }),
+      ...(auth.credentials.totp_secret && {
+        totp_secret: auth.credentials.totp_secret.replace(/\s/g, ''),
+      }),
       ...(auth.credentials.email_login && {
         email_login: {
           address: auth.credentials.email_login.address.trim(),
           password: auth.credentials.email_login.password,
           ...(auth.credentials.email_login.totp_secret && {
-            totp_secret: auth.credentials.email_login.totp_secret.trim(),
+            totp_secret: auth.credentials.email_login.totp_secret.replace(/\s/g, ''),
           }),
         },
       }),

apps/worker/src/paths.ts

@@ -9,6 +9,9 @@ const WORKER_ROOT = path.resolve(import.meta.dirname, '..');
 export const PROMPTS_DIR = path.join(WORKER_ROOT, 'prompts');
 export const CONFIGS_DIR = path.join(WORKER_ROOT, 'configs');
 
+/** Bundled Typst template that renders report.json into the PDF report. */
+export const TYPST_TEMPLATE = path.join(WORKER_ROOT, 'templates', 'typst', 'report.typ');
+
 /** Compiled pi extension dir that enforces bounded `bash` timeouts (resolved from dist/) */
 export const BASH_TIMEOUT_EXTENSION_DIR = path.join(import.meta.dirname, 'ai', 'extensions', 'bash-timeout');
 
@@ -28,8 +31,14 @@ export const INTERNAL_DIR = '.shannon';
 /** Filename of the assembled report inside the deliverables dir (internal, source of the surfaced copy) */
 export const ASSEMBLED_REPORT_FILENAME = 'comprehensive_security_assessment_report.md';
 
-/** Filename of the human-facing final report surfaced at the run directory root */
-export const FINAL_REPORT_FILENAME = 'Security-Assessment-Report.md';
+/** Filename of the compiled PDF report inside the deliverables dir (internal, source of the surfaced copy) */
+export const ASSEMBLED_REPORT_PDF_FILENAME = 'comprehensive_security_assessment_report.pdf';
+
+/** Filename of the human-facing PDF report surfaced at the run directory root */
+export const FINAL_REPORT_PDF_FILENAME = 'Security-Assessment-Report.pdf';
+
+/** Filename of the human-facing markdown report surfaced at the run directory root, alongside the PDF */
+export const FINAL_REPORT_MD_FILENAME = 'Security-Assessment-Report.md';
 
 /** Structured findings the report agent emits; the markdown report is rendered from it. */
 export const REPORT_JSON_FILENAME = 'report.json';

apps/worker/src/services/pdf-renderer.ts

@@ -0,0 +1,98 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Typst PDF renderer.
+ *
+ * Adapts the structured report.json into the Typst-shaped schema and compiles
+ * it to a PDF with the bundled report.typ template. Compilation runs in an
+ * isolated temp dir: the template is copied in and the adapted JSON is written
+ * beside it so `--root` can scope every file read to that dir, matching how the
+ * template resolves `--input data=/data.json`.
+ *
+ * The `typst` binary is installed in the worker image and resolved from PATH.
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { copyFile, cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { adaptReportToTypst } from './report-json-adapter.js';
+import type { ReportData } from './report-renderer.js';
+
+const execFileAsync = promisify(execFile);
+
+const DEFAULT_TESTER = 'Shannon';
+const DEFAULT_BRAND = 'Shannon | AI Pentester by Keygraph';
+
+const DATA_FILENAME = 'data.json';
+const TEMPLATE_FILENAME = 'report.typ';
+const OUTPUT_FILENAME = 'report.pdf';
+
+export interface RenderReportPdfOptions {
+  /** Structured report data (report.json contents), pre-assembly. */
+  readonly reportData: ReportData;
+  /** Absolute path to the bundled report.typ template. */
+  readonly templatePath: string;
+  /** Absolute path where the compiled PDF should be written. */
+  readonly outputPath: string;
+  /** Name shown on the cover/footer. Defaults to "Shannon". */
+  readonly tester?: string;
+  /** Wordmark shown on the cover. Defaults to "Shannon | AI Pentester by Keygraph". */
+  readonly brand?: string;
+}
+
+/**
+ * Compile the report to a PDF at `outputPath`.
+ *
+ * Throws if adaptation or `typst compile` fails; callers treat the PDF as a
+ * secondary artifact and should not let a failure here fail the run.
+ */
+export async function renderReportPdf(options: RenderReportPdfOptions): Promise<void> {
+  const { reportData, templatePath, outputPath } = options;
+  const tester = options.tester ?? DEFAULT_TESTER;
+  const brand = options.brand ?? DEFAULT_BRAND;
+
+  const typstData = adaptReportToTypst(reportData);
+
+  const workDir = await mkdtemp(path.join(tmpdir(), 'shannon-typst-'));
+  try {
+    const templateInWorkDir = path.join(workDir, TEMPLATE_FILENAME);
+    const dataInWorkDir = path.join(workDir, DATA_FILENAME);
+    const pdfInWorkDir = path.join(workDir, OUTPUT_FILENAME);
+
+    await copyFile(templatePath, templateInWorkDir);
+
+    // Ship the template's assets (e.g. the cover logo) so `--root`-scoped image reads resolve.
+    const assetsDir = path.join(path.dirname(templatePath), 'assets');
+    if (existsSync(assetsDir)) {
+      await cp(assetsDir, path.join(workDir, 'assets'), { recursive: true });
+    }
+
+    await writeFile(dataInWorkDir, JSON.stringify(typstData), 'utf-8');
+
+    await execFileAsync('typst', [
+      'compile',
+      '--root',
+      workDir,
+      '--input',
+      `data=/${DATA_FILENAME}`,
+      '--input',
+      `tester=${tester}`,
+      '--input',
+      `brand=${brand}`,
+      templateInWorkDir,
+      pdfInWorkDir,
+    ]);
+
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await copyFile(pdfInWorkDir, outputPath);
+  } finally {
+    await rm(workDir, { recursive: true, force: true });
+  }
+}

apps/worker/src/services/preflight.ts

@@ -36,10 +36,13 @@ import {
 } from '@earendil-works/pi-coding-agent';
 import { glob } from 'zx';
 import {
+  type CuratedProviderId,
   createModelRuntime,
+  GENERIC_API_KEY_ENV,
   type ModelSpec,
   type OpenAiFormat,
-  type ProviderId,
+  PI_CATALOG_URL,
+  piAuthPresent,
   resolveGatewayFormat,
   resolveModel,
   resolveModelSpec,
@@ -179,7 +182,7 @@ type RuleKind = 'avoid' | 'focus';
 interface MissingCodePath {
   kind: RuleKind;
   value: string;
-  description: string;
+  description?: string;
 }
 
 async function validateCodePathsExist(
@@ -202,12 +205,16 @@ async function validateCodePathsExist(
   const missing: MissingCodePath[] = [];
   for (const { kind, rule } of tagged) {
     if (!(await patternMatchesAny(repoPath, rule.value))) {
-      missing.push({ kind, value: rule.value, description: rule.description });
+      const entry: MissingCodePath = { kind, value: rule.value };
+      if (rule.description) {
+        entry.description = rule.description;
+      }
+      missing.push(entry);
     }
   }
 
   if (missing.length > 0) {
-    const lines = missing.map((m) => `[${m.kind}] '${m.value}' — ${m.description}`);
+    const lines = missing.map((m) => `[${m.kind}] '${m.value}'${m.description ? ` - ${m.description}` : ''}`);
     return err(
       new PentestError(
         `code_path rules don't match any file or directory in the repo:\n  - ${lines.join('\n  - ')}\n` +
@@ -273,17 +280,24 @@ async function probeCredentialsWithPi(
   return ok(undefined);
 }
 
-/** Credential env var a provider reads, for "credential missing" messages. */
-const PROVIDER_CREDENTIAL_HINT: Readonly<Record<ProviderId, string>> = {
+/** Credential env var a curated provider reads, for "credential missing" messages. */
+const PROVIDER_CREDENTIAL_HINT: Readonly<Record<CuratedProviderId, string>> = {
   anthropic: 'ANTHROPIC_API_KEY (or CLAUDE_CODE_OAUTH_TOKEN)',
   openai: 'OPENAI_API_KEY',
   xai: 'XAI_API_KEY',
   'amazon-bedrock': 'AWS_BEARER_TOKEN_BEDROCK and AWS_REGION',
 };
 
+/** Which variable to set when a provider's credential is missing. */
+function credentialHint(providerId: string): string {
+  const curated = (PROVIDER_CREDENTIAL_HINT as Record<string, string | undefined>)[providerId];
+  return curated ?? GENERIC_API_KEY_ENV;
+}
+
 /** Human-readable label for which credential path a run is using. */
-function describeAuth(providerId: ProviderId, baseUrl: string | undefined): string {
+function describeAuth(providerId: string, baseUrl: string | undefined): string {
   if (baseUrl) return `custom endpoint (${baseUrl})`;
+  if (piAuthPresent()) return `${providerId} credentials from pi auth.json`;
   if (providerId === 'amazon-bedrock') return 'Bedrock bearer token';
   return `${providerId} API key`;
 }
@@ -329,12 +343,14 @@ async function validateCredentials(logger: ActivityLogger): Promise<Result<void,
     );
   }
 
+  // With a mounted pi auth.json the env-var checks don't apply — step 5's probe validates it.
   const isBedrock = spec.providerId === 'amazon-bedrock';
-  const missing = isBedrock ? ['AWS_REGION', 'AWS_BEARER_TOKEN_BEDROCK'].filter((n) => !process.env[n]) : [];
-  if (missing.length > 0 || (!isBedrock && !credentials.apiKey)) {
+  const missing =
+    isBedrock && !piAuthPresent() ? ['AWS_REGION', 'AWS_BEARER_TOKEN_BEDROCK'].filter((n) => !process.env[n]) : [];
+  if (!piAuthPresent() && (missing.length > 0 || (!isBedrock && !credentials.apiKey))) {
     return err(
       new PentestError(
-        `No credentials found for provider "${spec.providerId}". Set ${PROVIDER_CREDENTIAL_HINT[spec.providerId]} in .env.`,
+        `No credentials found for provider "${spec.providerId}". Set ${credentialHint(spec.providerId)} in .env.`,
         'config',
         false,
         { providerId: spec.providerId, ...(missing.length > 0 && { missing }) },
@@ -352,7 +368,7 @@ async function validateCredentials(logger: ActivityLogger): Promise<Result<void,
   if (!baseModel) {
     return err(
       new PentestError(
-        `Model not found in pi registry: provider="${spec.providerId}" model="${spec.modelId}". Check SHANNON_AI_MODEL.`,
+        `Model not found in pi registry: provider="${spec.providerId}" model="${spec.modelId}". Check SHANNON_AI_MODEL — browse valid providers and models at ${PI_CATALOG_URL}.`,
         'config',
         false,
         { providerId: spec.providerId, modelId: spec.modelId },

apps/worker/src/services/prompt-manager.ts

@@ -12,61 +12,32 @@ import type { Authentication, DistributedConfig, DistributedReportConfig, Rule,
 import { isGlobPattern } from '../utils/glob.js';
 import { handlePromptError, PentestError } from './error-handling.js';
 
+function renderRuleLine(tag: string, value: string, description?: string): string {
+  const base = `- ${tag} ${value}`;
+  return description ? `${base} - ${description}` : base;
+}
+
+function renderUrlRules(rules: Rule[]): string {
+  if (rules.length === 0) return 'None';
+  return rules.map((r) => renderRuleLine(`[${r.type.toUpperCase()}]`, r.value, r.description)).join('\n');
+}
+
 function renderCodePathRules(rules: Rule[]): string {
   const filtered = rules.filter((r) => r.type === 'code_path');
   if (filtered.length === 0) return 'None';
   return filtered
-    .map((r) => {
-      const kind = isGlobPattern(r.value) ? '[GLOB]' : '[FILE]';
-      return `- ${r.value} ${kind} — ${r.description}`;
-    })
+    .map((r) => renderRuleLine(isGlobPattern(r.value) ? '[GLOB]' : '[FILE]', r.value, r.description))
     .join('\n');
 }
 
-interface VulnSummarySpec {
-  readonly heading: string;
-  readonly evidenceSection: string;
-  readonly noneFoundLabel: string;
-}
-
-const VULN_SUMMARY_SPECS: Record<VulnClass, VulnSummarySpec> = {
-  auth: {
-    heading: 'Authentication Vulnerabilities',
-    evidenceSection: 'Authentication Exploitation Evidence',
-    noneFoundLabel: 'authentication',
-  },
-  authz: {
-    heading: 'Authorization Vulnerabilities',
-    evidenceSection: 'Authorization Exploitation Evidence',
-    noneFoundLabel: 'authorization',
-  },
-  xss: {
-    heading: 'Cross-Site Scripting (XSS) Vulnerabilities',
-    evidenceSection: 'XSS Exploitation Evidence',
-    noneFoundLabel: 'XSS',
-  },
-  injection: {
-    heading: 'SQL/Command Injection Vulnerabilities',
-    evidenceSection: 'Injection Exploitation Evidence',
-    noneFoundLabel: 'SQL or command injection',
-  },
-  ssrf: {
-    heading: 'Server-Side Request Forgery (SSRF) Vulnerabilities',
-    evidenceSection: 'SSRF Exploitation Evidence',
-    noneFoundLabel: 'SSRF',
-  },
+const VULN_CLASS_HEADINGS: Record<VulnClass, string> = {
+  auth: 'Authentication Vulnerabilities',
+  authz: 'Authorization Vulnerabilities',
+  xss: 'Cross-Site Scripting (XSS) Vulnerabilities',
+  injection: 'SQL/Command Injection Vulnerabilities',
+  ssrf: 'Server-Side Request Forgery (SSRF) Vulnerabilities',
 };
 
-function renderVulnSummarySubsections(selected: readonly VulnClass[]): string {
-  const classes = selected.length > 0 ? selected : (Object.keys(VULN_SUMMARY_SPECS) as VulnClass[]);
-  return classes
-    .map((cls) => {
-      const spec = VULN_SUMMARY_SPECS[cls];
-      return `**${spec.heading}:**\n{Check for "${spec.evidenceSection}" section. Include actually exploited vulnerabilities and those blocked by security controls. Exclude theoretical vulnerabilities requiring internal network access. If vulnerabilities exist, summarize their impact and severity. If section is missing or empty, state: "No ${spec.noneFoundLabel} vulnerabilities were found."}`;
-    })
-    .join('\n\n');
-}
-
 /**
  * Renders the <not_assessed_classes> block. Empty when every class completed.
  *
@@ -86,9 +57,8 @@ function renderNotAssessedClassesBlock(failed: readonly VulnClass[] = []): strin
   ];
 
   for (const cls of classes) {
-    const spec = VULN_SUMMARY_SPECS[cls];
     lines.push(
-      `- ${spec.heading}: analysis did not complete; this class was NOT assessed. Absence of findings here does not indicate the class is clean.`,
+      `- ${VULN_CLASS_HEADINGS[cls]}: analysis did not complete; this class was NOT assessed. Absence of findings here does not indicate the class is clean.`,
     );
   }
 
@@ -103,13 +73,13 @@ function renderNotAssessedClassesBlock(failed: readonly VulnClass[] = []): strin
 /**
  * Which configured filters this run can actually enforce.
  *
- * The two ratings are mode-exclusive (see ../collectors/finding-collector.ts): an exploited
- * finding carries `severity`, an analysed one carries `confidence`. Handing the agent a
- * threshold for the rating its findings do not have is a directive it cannot honor.
+ * Every finding carries `severity` (see ../collectors/finding-collector.ts), so a severity
+ * threshold always applies. `confidence` exists only on an analysed finding — handing an
+ * exploit run a confidence threshold is a directive it cannot honor.
  */
 function applicableFilters(report: DistributedReportConfig | undefined, exploitEnabled: boolean) {
   return {
-    severity: Boolean(report?.min_severity) && exploitEnabled,
+    severity: Boolean(report?.min_severity),
     confidence: Boolean(report?.min_confidence) && !exploitEnabled,
     guidance: Boolean(report?.guidance?.trim()),
   };
@@ -375,8 +345,8 @@ async function interpolateVariables(
     if (avoidUrlRules.length === 0 && focusUrlRules.length === 0) {
       result = result.replace(/<rules>[\s\S]*?<\/rules>\s*/g, '');
     } else {
-      const avoidStr = avoidUrlRules.length > 0 ? avoidUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
-      const focusStr = focusUrlRules.length > 0 ? focusUrlRules.map((r) => `- ${r.description}`).join('\n') : 'None';
+      const avoidStr = renderUrlRules(avoidUrlRules);
+      const focusStr = renderUrlRules(focusUrlRules);
       result = replaceLiteral(result, /{{RULES_AVOID}}/g, avoidStr);
       result = replaceLiteral(result, /{{RULES_FOCUS}}/g, focusStr);
     }
@@ -416,7 +386,6 @@ async function interpolateVariables(
       /{{VULN_CLASSES_TESTED}}/g,
       vulnClasses.length > 0 ? vulnClasses.join(', ') : 'injection, xss, auth, authz, ssrf',
     );
-    result = replaceLiteral(result, /{{VULN_SUMMARY_SUBSECTIONS}}/g, renderVulnSummarySubsections(vulnClasses));
     result = replaceLiteral(
       result,
       /{{NOT_ASSESSED_CLASSES}}/g,
@@ -432,19 +401,12 @@ async function interpolateVariables(
     result = result.replace(/<\/?(?:exploit|analysis)_mode_[a-z_]+>\n?/g, '');
 
     result = replaceLiteral(result, /{{EXPLOITATION}}/g, exploitEnabled ? 'enabled' : 'disabled');
-    result = replaceLiteral(result, /{{REPORT_VULN_HEADING}}/g, exploitEnabled ? 'Exploitation Evidence' : 'Findings');
     result = replaceLiteral(
       result,
       /{{REPORT_VULN_SUBHEADING}}/g,
       exploitEnabled ? 'Successfully Exploited Vulnerabilities' : 'Identified Vulnerabilities',
     );
 
-    if (config?.report?.min_severity && !exploitEnabled) {
-      logger.warn(
-        `report.min_severity="${config.report.min_severity}" is ignored when exploit=false: an ` +
-          'analysis-only run rates findings by confidence, not severity. Use report.min_confidence.',
-      );
-    }
     if (config?.report?.min_confidence && exploitEnabled) {
       logger.warn(
         `report.min_confidence="${config.report.min_confidence}" is ignored when exploit=true: an ` +

apps/worker/src/services/report-json-adapter.ts

@@ -0,0 +1,293 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * Programmatic adapter: report.json → Typst ReportData JSON.
+ *
+ * Converts the renderer-neutral structured report output (produced by the
+ * finding-collector + set-report-meta CLI) into the Typst-specific schema that
+ * report.typ consumes.
+ *
+ * All Typst-specific concepts (PascalCase enums, computed aggregations,
+ * exploitedByType grouping) are confined to this file. The rest of the
+ * pipeline knows nothing about the Typst shape.
+ */
+
+import type { AddFindingInput, AdditionalSection, StepItem, StructuredStep } from '../collectors/finding-collector.js';
+import type {
+  ExploitsReportData,
+  FindingsReportData,
+  TypstCategory,
+  TypstConfidence,
+  ReportData as TypstReportData,
+  TypstSeverity,
+  TypstStatus,
+} from './report-output-schema.js';
+import type { ReportData } from './report-renderer.js';
+
+// ============================================================================
+// CASING TRANSFORMS
+// ============================================================================
+
+const SEVERITY_MAP: Record<string, TypstSeverity> = {
+  critical: 'Critical',
+  high: 'High',
+  medium: 'Medium',
+  low: 'Low',
+};
+
+const STATUS_MAP: Record<string, TypstStatus> = {
+  exploited: 'Exploited',
+  out_of_scope: 'OutOfScope',
+  blocked_by_constraints: 'BlockedByConstraints',
+  false_positive: 'FalsePositive',
+};
+
+const CONFIDENCE_MAP: Record<string, TypstConfidence> = {
+  high: 'High',
+  medium: 'Medium',
+  low: 'Low',
+};
+
+const VALID_CATEGORIES = new Set<TypstCategory>([
+  'Authentication',
+  'Authorization',
+  'XSS',
+  'Injection',
+  'SSRF',
+  'Other',
+]);
+
+function toTypstSeverity(s: string): TypstSeverity {
+  return SEVERITY_MAP[s] ?? 'Low';
+}
+
+function toTypstStatus(s: string): TypstStatus {
+  return STATUS_MAP[s] ?? 'Exploited';
+}
+
+function toTypstConfidence(s: string): TypstConfidence {
+  return CONFIDENCE_MAP[s] ?? 'Medium';
+}
+
+function toTypstCategory(s: string): TypstCategory {
+  if (VALID_CATEGORIES.has(s as TypstCategory)) return s as TypstCategory;
+  return 'Other';
+}
+
+// ============================================================================
+// STEP / ITEM TRANSFORMS
+// ============================================================================
+
+function adaptStepItem(item: StepItem): StepItem {
+  return item;
+}
+
+function adaptStep(step: StructuredStep, index: number): { number: number; title?: string; items: StepItem[] } {
+  return {
+    number: index + 1,
+    ...(step.title && { title: step.title }),
+    items: step.items.map(adaptStepItem),
+  };
+}
+
+function adaptAdditionalSection(section: AdditionalSection): { heading: string; items: StepItem[] } {
+  return {
+    heading: section.heading,
+    items: section.items.map(adaptStepItem),
+  };
+}
+
+// ============================================================================
+// AGGREGATION HELPERS
+// ============================================================================
+
+interface CategoryGroup {
+  category: TypstCategory;
+  findings: AddFindingInput[];
+}
+
+function groupByCategory(findings: readonly AddFindingInput[]): CategoryGroup[] {
+  const map = new Map<TypstCategory, AddFindingInput[]>();
+  for (const f of findings) {
+    const cat = toTypstCategory(f.category);
+    const list = map.get(cat) ?? [];
+    list.push(f);
+    map.set(cat, list);
+  }
+  return Array.from(map.entries()).map(([category, fs]) => ({ category, findings: fs }));
+}
+
+function countBySeverity(findings: readonly AddFindingInput[]): Record<TypstSeverity, number> {
+  const counts: Record<string, number> = {
+    Critical: 0,
+    High: 0,
+    Medium: 0,
+    Low: 0,
+  };
+  for (const f of findings) {
+    const sev = toTypstSeverity(f.severity);
+    counts[sev] = (counts[sev] ?? 0) + 1;
+  }
+  return counts as Record<TypstSeverity, number>;
+}
+
+// ============================================================================
+// EXPLOIT MODE ADAPTER
+// ============================================================================
+
+function adaptExploitsMode(data: ReportData): ExploitsReportData {
+  const { report_meta, findings } = data;
+  const groups = groupByCategory(findings);
+  const sevCounts = countBySeverity(findings);
+
+  const statusCounts = { Exploited: 0, OutOfScope: 0, BlockedByConstraints: 0, FalsePositive: 0 };
+  for (const f of findings) {
+    const s = toTypstStatus(f.status ?? 'exploited');
+    statusCounts[s]++;
+  }
+
+  const exploitedFindings = findings.filter((f) => (f.status ?? 'exploited') === 'exploited');
+
+  return {
+    mode: 'exploits' as const,
+    meta: {
+      target: report_meta.target,
+      assessmentDate: report_meta.assessment_date,
+      classification: 'CONFIDENTIAL',
+    },
+    scope: report_meta.scope,
+    exploitedByType: groups.map((g) => {
+      const exploited = g.findings.filter((f) => (f.status ?? 'exploited') === 'exploited');
+      if (exploited.length === 0) {
+        return {
+          category: g.category,
+          narrative: `No ${g.category.toLowerCase()} vulnerabilities were successfully exploited during this assessment.`,
+        };
+      }
+      return {
+        category: g.category,
+        bullets: exploited.map((f) => ({ id: f.finding_id, description: f.title })),
+      };
+    }),
+    summary: {
+      totalIdentified: findings.length,
+      successfullyExploited: exploitedFindings.length,
+      exploitedBreakdown: groups
+        .map((g) => ({
+          category: g.category,
+          count: g.findings.filter((f) => (f.status ?? 'exploited') === 'exploited').length,
+        }))
+        .filter((e) => e.count > 0),
+      criticalFindings: findings.filter((f) => f.severity === 'critical').map((f) => `${f.finding_id}: ${f.title}`),
+    },
+    findings: findings.map((f) => ({
+      id: f.finding_id,
+      title: f.title,
+      category: toTypstCategory(f.category),
+      severity: toTypstSeverity(f.severity),
+      status: toTypstStatus(f.status ?? 'exploited'),
+      summary: {
+        vulnerableLocation: f.vulnerable_location,
+        overview: f.overview,
+        impact: f.impact,
+      },
+      // This branch only runs for an exploitative report, where the schema made these
+      // required. The fallbacks keep the superset type honest rather than assuming.
+      prerequisites: f.prerequisites ?? '',
+      exploitationSteps: (f.exploitation_steps ?? []).map(adaptStep),
+      proofOfImpact: (f.proof_of_impact ?? []).map(adaptStepItem),
+      ...(f.notes && f.notes.length > 0 && { notes: f.notes.map(adaptStepItem) }),
+      ...(f.additional_sections &&
+        f.additional_sections.length > 0 && {
+          additionalSections: f.additional_sections.map(adaptAdditionalSection),
+        }),
+    })),
+    derivedCounts: {
+      bySeverity: sevCounts,
+      byStatus: statusCounts,
+    },
+  };
+}
+
+// ============================================================================
+// FINDINGS MODE ADAPTER
+// ============================================================================
+
+function adaptFindingsMode(data: ReportData): FindingsReportData {
+  const { report_meta, findings } = data;
+  const groups = groupByCategory(findings);
+  const sevCounts = countBySeverity(findings);
+
+  const confidenceCounts = { High: 0, Medium: 0, Low: 0 };
+  for (const f of findings) {
+    const c = toTypstConfidence(f.confidence ?? 'medium');
+    confidenceCounts[c]++;
+  }
+
+  return {
+    mode: 'findings' as const,
+    meta: {
+      target: report_meta.target,
+      assessmentDate: report_meta.assessment_date,
+      classification: 'CONFIDENTIAL',
+    },
+    scope: report_meta.scope,
+    identifiedByType: groups.map((g) => {
+      if (g.findings.length === 0) {
+        return {
+          category: g.category,
+          narrative: `No ${g.category.toLowerCase()} vulnerabilities were identified during this assessment.`,
+        };
+      }
+      return {
+        category: g.category,
+        bullets: g.findings.map((f) => ({ id: f.finding_id, description: f.title })),
+      };
+    }),
+    summary: {
+      totalIdentified: findings.length,
+      identifiedBreakdown: groups.map((g) => ({
+        category: g.category,
+        count: g.findings.length,
+      })),
+      criticalFindings: findings.filter((f) => f.severity === 'critical').map((f) => `${f.finding_id}: ${f.title}`),
+    },
+    findings: findings.map((f) => ({
+      id: f.finding_id,
+      title: f.title,
+      category: toTypstCategory(f.category),
+      severity: toTypstSeverity(f.severity),
+      confidence: toTypstConfidence(f.confidence ?? 'medium'),
+      summary: {
+        vulnerableLocation: f.vulnerable_location,
+        overview: f.overview,
+        impact: f.impact,
+      },
+      ...(f.notes && f.notes.length > 0 && { notes: f.notes.map(adaptStepItem) }),
+      ...(f.additional_sections &&
+        f.additional_sections.length > 0 && {
+          additionalSections: f.additional_sections.map(adaptAdditionalSection),
+        }),
+    })),
+    derivedCounts: {
+      bySeverity: sevCounts,
+      byConfidence: confidenceCounts,
+    },
+  };
+}
+
+// ============================================================================
+// PUBLIC API
+// ============================================================================
+
+export function adaptReportToTypst(data: ReportData): TypstReportData {
+  const exploitEnabled = data.report_meta.exploit ?? true;
+  if (exploitEnabled) {
+    return adaptExploitsMode(data);
+  }
+  return adaptFindingsMode(data);
+}

apps/worker/src/services/report-output-schema.ts

@@ -0,0 +1,157 @@
+// Copyright (C) 2025 Keygraph, Inc.
+//
+// This program is free software: you can redistribute it and/or modify
+// it under the terms of the GNU Affero General Public License version 3
+// as published by the Free Software Foundation.
+
+/**
+ * TypeScript types for the structured report the Typst template consumes, in two
+ * shapes keyed by a `mode` discriminator: `exploits` (exploit=true) and `findings`
+ * (exploit=false, analysis-only). Types only — the object is built programmatically
+ * in report-json-adapter.ts, so these exist to keep the adapter and report.typ in sync.
+ */
+
+// === Shared primitives ===
+
+export type TypstSeverity = 'Critical' | 'High' | 'Medium' | 'Low';
+export type TypstStatus = 'Exploited' | 'OutOfScope' | 'BlockedByConstraints' | 'FalsePositive';
+export type TypstConfidence = 'High' | 'Medium' | 'Low';
+export type TypstCategory = 'Authentication' | 'Authorization' | 'XSS' | 'Injection' | 'SSRF' | 'Other';
+
+export interface CodeBlock {
+  readonly language: string;
+  readonly content: string;
+}
+
+export type StepItem =
+  | { readonly kind: 'prose'; readonly text: string }
+  | { readonly kind: 'code'; readonly block: CodeBlock };
+
+export interface Step {
+  readonly number: number;
+  readonly title?: string;
+  readonly items: readonly StepItem[];
+}
+
+export interface AdditionalSection {
+  readonly heading: string;
+  readonly items: readonly StepItem[];
+}
+
+export interface FindingSummary {
+  readonly vulnerableLocation: string;
+  readonly overview: string;
+  readonly impact: string;
+}
+
+export interface Meta {
+  readonly target: string;
+  readonly assessmentDate: string;
+  readonly tester?: string;
+  readonly application?: string;
+  readonly classification: string;
+}
+
+export interface CategoryCount {
+  readonly category: TypstCategory;
+  readonly count: number;
+  readonly note?: string;
+}
+
+export type SeverityCounts = Record<TypstSeverity, number>;
+export type StatusCounts = Record<TypstStatus, number>;
+export type ConfidenceCounts = Record<TypstConfidence, number>;
+
+export interface TypeEntryBullet {
+  readonly id: string;
+  readonly description: string;
+}
+
+// === Exploits-mode schema ===
+
+export interface ExploitFinding {
+  readonly id: string;
+  readonly title: string;
+  readonly category: TypstCategory;
+  readonly severity: TypstSeverity;
+  readonly status: TypstStatus;
+  readonly summary: FindingSummary;
+  readonly prerequisites: string;
+  readonly exploitationSteps: readonly Step[];
+  readonly proofOfImpact: readonly StepItem[];
+  readonly notes?: readonly StepItem[];
+  readonly additionalSections?: readonly AdditionalSection[];
+}
+
+export interface ExploitedByTypeEntry {
+  readonly category: TypstCategory;
+  readonly bullets?: readonly TypeEntryBullet[];
+  readonly narrative?: string;
+}
+
+export interface ExploitsReportData {
+  readonly mode: 'exploits';
+  readonly meta: Meta;
+  readonly scope: string;
+  readonly exploitedByType: readonly ExploitedByTypeEntry[];
+  readonly summary: {
+    readonly totalIdentified: number;
+    readonly successfullyExploited: number;
+    readonly exploitedBreakdown: readonly CategoryCount[];
+    readonly outOfScope?: {
+      readonly total: number;
+      readonly breakdown?: readonly CategoryCount[];
+      readonly note?: string;
+    };
+    readonly blockedByConstraints?: {
+      readonly total: number;
+      readonly note?: string;
+    };
+    readonly criticalFindings: readonly string[];
+  };
+  readonly findings: readonly ExploitFinding[];
+  readonly derivedCounts: {
+    readonly bySeverity: SeverityCounts;
+    readonly byStatus: StatusCounts;
+  };
+}
+
+// === Findings-mode schema (analysis-only, exploit=false runs) ===
+
+export interface AnalysisFinding {
+  readonly id: string;
+  readonly title: string;
+  readonly category: TypstCategory;
+  readonly severity: TypstSeverity;
+  readonly confidence: TypstConfidence;
+  readonly summary: FindingSummary;
+  readonly notes?: readonly StepItem[];
+  readonly additionalSections?: readonly AdditionalSection[];
+}
+
+export interface IdentifiedByTypeEntry {
+  readonly category: TypstCategory;
+  readonly bullets?: readonly TypeEntryBullet[];
+  readonly narrative?: string;
+}
+
+export interface FindingsReportData {
+  readonly mode: 'findings';
+  readonly meta: Meta;
+  readonly scope: string;
+  readonly identifiedByType: readonly IdentifiedByTypeEntry[];
+  readonly summary: {
+    readonly totalIdentified: number;
+    readonly identifiedBreakdown: readonly CategoryCount[];
+    readonly criticalFindings: readonly string[];
+  };
+  readonly findings: readonly AnalysisFinding[];
+  readonly derivedCounts: {
+    readonly bySeverity: SeverityCounts;
+    readonly byConfidence: ConfidenceCounts;
+  };
+}
+
+// === Discriminated union for downstream consumers that handle both ===
+
+export type ReportData = ExploitsReportData | FindingsReportData;

apps/worker/src/services/report-renderer.ts

@@ -263,7 +263,16 @@ export function renderReport(data: ReportData): string {
     sections.push(`### ${cat}`);
     sections.push('');
     for (const f of catFindings) {
-      const suffix = f.severity ? ` (${titleCase(f.severity)})` : '';
+      // Both ratings when the mode produced both. Confidence is labelled so it is never
+      // read as a severity in the position where a severity usually sits.
+      const ratings: string[] = [];
+      if (f.severity) {
+        ratings.push(titleCase(f.severity));
+      }
+      if (f.confidence) {
+        ratings.push(`${titleCase(f.confidence)} confidence`);
+      }
+      const suffix = ratings.length > 0 ? ` (${ratings.join(', ')})` : '';
       sections.push(`- **${f.finding_id}:** ${f.title}${suffix}`);
     }
     sections.push('');

apps/worker/src/services/reporting.ts

@@ -7,8 +7,10 @@
 import { fs, path } from 'zx';
 import {
   ASSEMBLED_REPORT_FILENAME,
+  ASSEMBLED_REPORT_PDF_FILENAME,
   deliverablesDir,
-  FINAL_REPORT_FILENAME,
+  FINAL_REPORT_MD_FILENAME,
+  FINAL_REPORT_PDF_FILENAME,
   resolveSessionJsonPath,
   SARIF_FILENAME,
 } from '../paths.js';
@@ -174,7 +176,8 @@ export async function injectModelIntoReport(
 /**
  * Surface the run's deliverables at the run directory's top level, so a customer opening the run
  * folder sees the report without digging through internals. Sources stay in the deliverables dir
- * (git-checkpointed, used by resume).
+ * (git-checkpointed, used by resume). Both the PDF and the markdown report are surfaced here as the
+ * customer-facing copies.
  *
  * The SARIF log is surfaced beside it when present, since a CI step consuming it needs a stable
  * path and cannot be expected to reach into the internals directory. It is absent whenever the
@@ -188,13 +191,22 @@ export async function copyReportToRunRoot(
 ): Promise<void> {
   const dir = deliverablesDir(repoPath, deliverablesSubdir);
 
-  const source = path.join(dir, ASSEMBLED_REPORT_FILENAME);
-  if (await fs.pathExists(source)) {
-    const destination = path.join(runDir, FINAL_REPORT_FILENAME);
-    await fs.copy(source, destination, { overwrite: true });
-    logger.info(`Surfaced report at ${destination}`);
+  const pdfSource = path.join(dir, ASSEMBLED_REPORT_PDF_FILENAME);
+  if (await fs.pathExists(pdfSource)) {
+    const destination = path.join(runDir, FINAL_REPORT_PDF_FILENAME);
+    await fs.copy(pdfSource, destination, { overwrite: true });
+    logger.info(`Surfaced PDF report at ${destination}`);
   } else {
-    logger.warn(`Final report not found, skipping ${FINAL_REPORT_FILENAME}`);
+    logger.warn(`PDF report not found, skipping ${FINAL_REPORT_PDF_FILENAME}`);
+  }
+
+  const markdownSource = path.join(dir, ASSEMBLED_REPORT_FILENAME);
+  if (await fs.pathExists(markdownSource)) {
+    const destination = path.join(runDir, FINAL_REPORT_MD_FILENAME);
+    await fs.copy(markdownSource, destination, { overwrite: true });
+    logger.info(`Surfaced markdown report at ${destination}`);
+  } else {
+    logger.warn(`Markdown report not found, skipping ${FINAL_REPORT_MD_FILENAME}`);
   }
 
   const sarifSource = path.join(dir, SARIF_FILENAME);

apps/worker/src/services/sarif-renderer.ts

@@ -154,7 +154,7 @@ function buildMessageMarkdown(finding: AddFindingInput): string {
   parts.push('', '**Remediation**', '', finding.remediation);
   // Exploitation steps and proof of impact are deliberately absent: SARIF has no structural home
   // for them, and flattening them into prose would imply this file carries the evidence.
-  parts.push('', 'Full exploitation evidence: `Security-Assessment-Report.md`');
+  parts.push('', 'Full exploitation evidence: `Security-Assessment-Report.pdf`');
   return parts.join('\n');
 }
 

apps/worker/src/services/validate-authentication.ts

@@ -23,6 +23,7 @@ import type { ActivityLogger } from '../types/activity-logger.js';
 import type { AgentEndResult } from '../types/audit.js';
 import type { DistributedConfig } from '../types/config.js';
 import { ErrorCode } from '../types/errors.js';
+import type { AgentMetrics } from '../types/metrics.js';
 import { err, ok, type Result } from '../types/result.js';
 import { PentestError } from './error-handling.js';
 import { loadPrompt } from './prompt-manager.js';
@@ -97,7 +98,9 @@ export interface ValidateAuthInput {
   readonly cancellationSignal?: AbortSignal;
 }
 
-export async function validateAuthentication(input: ValidateAuthInput): Promise<Result<void, PentestError>> {
+export async function validateAuthentication(
+  input: ValidateAuthInput,
+): Promise<Result<AgentMetrics | null, PentestError>> {
   const {
     distributedConfig,
     repoPath,
@@ -113,7 +116,7 @@ export async function validateAuthentication(input: ValidateAuthInput): Promise<
 
   const authentication = distributedConfig.authentication;
   if (!authentication) {
-    return ok(undefined);
+    return ok(null);
   }
 
   logger.info('Validating authentication credentials with live browser...', {
@@ -160,9 +163,10 @@ export async function validateAuthentication(input: ValidateAuthInput): Promise<
     }
   }
 
+  const durationMs = Date.now() - startTime;
   const endResult: AgentEndResult = {
     attemptNumber,
-    duration_ms: Date.now() - startTime,
+    duration_ms: durationMs,
     cost_usd: result.cost || 0,
     success: classification.ok,
     ...(result.model !== undefined && { model: result.model }),
@@ -170,7 +174,21 @@ export async function validateAuthentication(input: ValidateAuthInput): Promise<
   };
   await auditSession.endAgent(AGENT_NAME, endResult);
 
-  return classification;
+  if (!classification.ok) {
+    return err(classification.error);
+  }
+
+  const metrics: AgentMetrics = {
+    durationMs,
+    inputTokens: result.inputTokens ?? null,
+    outputTokens: result.outputTokens ?? null,
+    cacheReadTokens: result.cacheReadTokens ?? null,
+    cacheWriteTokens: result.cacheWriteTokens ?? null,
+    costUsd: result.cost ?? null,
+    numTurns: result.turns ?? null,
+    ...(result.model !== undefined && { model: result.model }),
+  };
+  return ok(metrics);
 }
 
 async function verifySavedAuthState(stateFile: string, logger: ActivityLogger): Promise<Result<void, PentestError>> {
@@ -205,28 +223,32 @@ async function verifySavedAuthState(stateFile: string, logger: ActivityLogger):
     );
   }
 
-  const cookieCount = countStorageEntries(parsed, 'cookies');
-  const originCount = countStorageEntries(parsed, 'origins');
-  if (cookieCount === 0 && originCount === 0) {
+  const cookies = storageEntries(parsed, 'cookies');
+  const origins = storageEntries(parsed, 'origins');
+  if (!cookies || !origins) {
     return err(
       new PentestError(
-        `Preflight saved an authenticated session to ${stateFile}, but it contains no cookies or origins — the browser was not actually logged in.`,
+        `Preflight saved an authenticated session to ${stateFile}, but it is not a storage state — cookies and origins arrays are missing.`,
         'validation',
         true,
-        { stateFile, cookieCount, originCount },
+        { stateFile, hasCookies: !!cookies, hasOrigins: !!origins },
         ErrorCode.AGENT_EXECUTION_FAILED,
       ),
     );
   }
 
-  logger.info('Preflight authenticated session saved', { stateFile, cookieCount, originCount });
+  logger.info('Preflight authenticated session saved', {
+    stateFile,
+    cookieCount: cookies.length,
+    originCount: origins.length,
+  });
   return ok(undefined);
 }
 
-function countStorageEntries(parsed: unknown, key: 'cookies' | 'origins'): number {
-  if (typeof parsed !== 'object' || parsed === null) return 0;
+function storageEntries(parsed: unknown, key: 'cookies' | 'origins'): unknown[] | null {
+  if (typeof parsed !== 'object' || parsed === null) return null;
   const value = (parsed as Record<string, unknown>)[key];
-  return Array.isArray(value) ? value.length : 0;
+  return Array.isArray(value) ? value : null;
 }
 
 function classifyResult(

apps/worker/src/temporal/activities.ts

@@ -27,11 +27,13 @@ import type { WorkflowSummary } from '../audit/workflow-logger.js';
 import type { CheckpointContext } from '../interfaces/checkpoint-provider.js';
 import {
   ASSEMBLED_REPORT_FILENAME,
+  ASSEMBLED_REPORT_PDF_FILENAME,
   DEFAULT_DELIVERABLES_SUBDIR,
   deliverablesDir,
   REPORT_JSON_FILENAME,
   resolveSessionJsonPath,
   SARIF_FILENAME,
+  TYPST_TEMPLATE,
 } from '../paths.js';
 import { getAgentGitPaths } from '../services/agent-git-paths.js';
 import { getContainer, getOrCreateContainer, removeContainer } from '../services/container.js';
@@ -477,6 +479,30 @@ async function writeSarifIfEnabled(
   }
 }
 
+/**
+ * Compile the PDF report from the assembled report data.
+ *
+ * Failures are logged and swallowed — the PDF is a secondary artifact and must not fail a run
+ * whose report is already written.
+ */
+async function writePdfReport(
+  reportData: ReportData,
+  deliverablesPath: string,
+  logger: ReturnType<typeof createActivityLogger>,
+): Promise<void> {
+  try {
+    const { renderReportPdf } = await import('../services/pdf-renderer.js');
+    await renderReportPdf({
+      reportData,
+      templatePath: TYPST_TEMPLATE,
+      outputPath: path.join(deliverablesPath, ASSEMBLED_REPORT_PDF_FILENAME),
+    });
+    logger.info(`Wrote ${ASSEMBLED_REPORT_PDF_FILENAME}`);
+  } catch (error) {
+    logger.warn(`Failed to write ${ASSEMBLED_REPORT_PDF_FILENAME}: ${(error as Error).message}`);
+  }
+}
+
 export async function runReportAgent(input: ActivityInput, exploit: boolean): Promise<AgentMetrics> {
   const { createFindingCollector } = await import('../collectors/finding-collector.js');
   const { renderReport } = await import('../services/report-renderer.js');
@@ -532,6 +558,7 @@ export async function runReportAgent(input: ActivityInput, exploit: boolean): Pr
     await atomicWrite(path.join(deliverablesPath, ASSEMBLED_REPORT_FILENAME), renderReport(reportData));
     logger.info(`Wrote ${ASSEMBLED_REPORT_FILENAME} from structured data`);
 
+    await writePdfReport(reportData, deliverablesPath, logger);
     await writeSarifIfEnabled(input, exploit, reportData, deliverablesPath, logger);
   };
 
@@ -610,7 +637,7 @@ export async function runPreflightValidation(input: ActivityInput): Promise<void
  * block; otherwise surfaces a classified failure (failurePoint +
  * failureDetail in ApplicationFailure.details) on credential rejection.
  */
-export async function runAuthenticationValidation(input: ActivityInput): Promise<void> {
+export async function runAuthenticationValidation(input: ActivityInput): Promise<AgentMetrics | null> {
   const startTime = Date.now();
   const attemptNumber = Context.current().info.attempt;
 
@@ -628,13 +655,13 @@ export async function runAuthenticationValidation(input: ActivityInput): Promise
     if (isErr(configResult)) {
       // runPreflightValidation already validated parsing, so this is unexpected.
       logger.warn(`runAuthenticationValidation: config load failed unexpectedly: ${configResult.error.message}`);
-      return;
+      return null;
     }
 
     const distributedConfig = configResult.value;
     if (!distributedConfig?.authentication) {
       logger.info('No authentication configured — skipping credential validation');
-      return;
+      return null;
     }
 
     const auditSession = new AuditSession(sessionMetadata);
@@ -673,6 +700,8 @@ export async function runAuthenticationValidation(input: ActivityInput): Promise
       truncateStackTrace(failure);
       throw failure;
     }
+
+    return result.value;
   } catch (error) {
     if (error instanceof ApplicationFailure) {
       throw error;
@@ -1111,9 +1140,19 @@ export async function restoreGitCheckpoint(
 /**
  * Record a resume attempt in session.json and write resume header to workflow.log.
  */
+/**
+ * Register this resume's workflow id in session.json before loadResumeState (which can throw),
+ * so the CLI can resolve and follow the resume even when validation fails instead of timing out.
+ */
+export async function registerResumeAttempt(input: ActivityInput, terminatedWorkflows: string[]): Promise<void> {
+  const sessionMetadata = buildSessionMetadata(input);
+  const auditSession = new AuditSession(sessionMetadata);
+  await auditSession.initialize();
+  await auditSession.addResumeAttempt(input.workflowId, terminatedWorkflows);
+}
+
 export async function recordResumeAttempt(
   input: ActivityInput,
-  terminatedWorkflows: string[],
   checkpointHash: string,
   previousWorkflowId: string,
   completedAgents: string[],
@@ -1122,10 +1161,7 @@ export async function recordResumeAttempt(
   const auditSession = new AuditSession(sessionMetadata);
   await auditSession.initialize();
 
-  // Update session.json with resume attempt
-  await auditSession.addResumeAttempt(input.workflowId, terminatedWorkflows, checkpointHash);
-
-  // Write resume header to workflow.log
+  // session.json entry already added by registerResumeAttempt; here we only write the workflow.log header.
   await auditSession.logResumeHeader({
     previousWorkflowId,
     newWorkflowId: input.workflowId,

apps/worker/src/temporal/worker.ts

@@ -35,7 +35,12 @@ import { bundleWorkflowCode, NativeConnection, Worker } from '@temporalio/worker
 import dotenv from 'dotenv';
 import { sanitizeHostname } from '../audit/utils.js';
 import { parseConfig } from '../config-parser.js';
-import { ASSEMBLED_REPORT_FILENAME, deliverablesDir, FINAL_REPORT_FILENAME, resolveSessionJsonPath } from '../paths.js';
+import {
+  ASSEMBLED_REPORT_PDF_FILENAME,
+  deliverablesDir,
+  FINAL_REPORT_PDF_FILENAME,
+  resolveSessionJsonPath,
+} from '../paths.js';
 import type { VulnClass } from '../types/config.js';
 import { fileExists, readJson } from '../utils/file-io.js';
 import * as activities from './activities.js';
@@ -389,9 +394,9 @@ function copyDeliverables(repoPath: string, outputPath: string): void {
   }
 
   // Surface the report under its human-facing name alongside the raw deliverables
-  const assembledReport = path.join(outputDir, ASSEMBLED_REPORT_FILENAME);
-  if (fs.existsSync(assembledReport)) {
-    fs.copyFileSync(assembledReport, path.join(outputPath, FINAL_REPORT_FILENAME));
+  const assembledPdf = path.join(outputDir, ASSEMBLED_REPORT_PDF_FILENAME);
+  if (fs.existsSync(assembledPdf)) {
+    fs.copyFileSync(assembledPdf, path.join(outputPath, FINAL_REPORT_PDF_FILENAME));
   }
 
   console.log(`Copied ${files.length} deliverable(s) to ${outputPath}`);

apps/worker/src/temporal/workflows.ts

@@ -24,6 +24,7 @@
  */
 
 import {
+  ActivityCancellationType,
   ApplicationFailure,
   CancellationScope,
   isCancellation,
@@ -96,6 +97,8 @@ const acts = proxyActivities<typeof activities>({
   startToCloseTimeout: '2 hours',
   heartbeatTimeout: '60 minutes', // Extended for nested pi task execution
   retry: PRODUCTION_RETRY,
+  // Cancel promptly instead of waiting out startToCloseTimeout; the agent aborts on the signal.
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 // Activity proxy with testing retry configuration (fast)
@@ -103,6 +106,7 @@ const testActs = proxyActivities<typeof activities>({
   startToCloseTimeout: '30 minutes',
   heartbeatTimeout: '30 minutes', // Extended for sub-agent execution in testing
   retry: TESTING_RETRY,
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 // Retry configuration for preflight validation (short timeout, few retries)
@@ -119,6 +123,7 @@ const preflightActs = proxyActivities<typeof activities>({
   startToCloseTimeout: '2 minutes',
   heartbeatTimeout: '2 minutes',
   retry: PREFLIGHT_RETRY,
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 // Credential rejection is not retryable; transient provider errors get 3 attempts.
@@ -135,6 +140,7 @@ const authValidationActs = proxyActivities<typeof activities>({
   startToCloseTimeout: '10 minutes',
   heartbeatTimeout: '10 minutes',
   retry: AUTH_VALIDATION_RETRY,
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 /**
@@ -246,6 +252,10 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
   let resumeState: ResumeState | null = null;
 
   if (input.resumeFromWorkspace) {
+    // 0. Register the resume's workflow id in session.json before validation can fail, so the CLI
+    // can resolve and follow it instead of polling for an entry that never lands.
+    await a.registerResumeAttempt(activityInput, input.terminatedWorkflows || []);
+
     // 1. Load resume state (validates workspace, cross-checks deliverables)
     resumeState = await a.loadResumeState(
       input.resumeFromWorkspace,
@@ -277,10 +287,9 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
       return state;
     }
 
-    // 4. Record this resume attempt in session.json and workflow.log
+    // 4. Write the resume header to workflow.log (the session.json entry was recorded in step 0)
     await a.recordResumeAttempt(
       activityInput,
-      input.terminatedWorkflows || [],
       resumeState.checkpointHash,
       resumeState.originalWorkflowId,
       resumeState.completedAgents,
@@ -480,7 +489,11 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
     // === Authentication Validation ===
     state.currentPhase = 'auth-validation';
     state.currentAgent = 'validate-authentication';
-    await authValidationActs.runAuthenticationValidation(activityInput);
+    const authMetrics = await authValidationActs.runAuthenticationValidation(activityInput);
+    // Null when no login ran (no-auth scan); left absent so status renders it skipped, not completed.
+    if (authMetrics) {
+      state.agentMetrics['validate-authentication'] = authMetrics;
+    }
     state.currentAgent = null;
     log.info('Authentication validation passed');
 

apps/worker/src/temporal/workspaces.ts

@@ -1,174 +0,0 @@
-#!/usr/bin/env node
-// Copyright (C) 2025 Keygraph, Inc.
-//
-// This program is free software: you can redistribute it and/or modify
-// it under the terms of the GNU Affero General Public License version 3
-// as published by the Free Software Foundation.
-
-/**
- * Workspace listing tool for Shannon.
- *
- * Reads workspaces/ directories, parses session.json files, and displays
- * a formatted table of all workspaces with status, duration, and cost.
- *
- * Usage:
- *   node dist/temporal/workspaces.js
- *
- * Environment:
- *   WORKSPACES_DIR - Override workspaces directory (default: ./workspaces)
- */
-
-import fs from 'node:fs/promises';
-import path from 'node:path';
-import { WORKSPACES_DIR as DEFAULT_WORKSPACES_DIR, resolveSessionJsonPath } from '../paths.js';
-
-interface SessionJson {
-  session: {
-    id: string;
-    webUrl: string;
-    status: 'in-progress' | 'completed' | 'failed';
-    createdAt: string;
-    completedAt?: string;
-  };
-  metrics: {
-    total_cost_usd: number;
-  };
-}
-
-interface WorkspaceInfo {
-  name: string;
-  url: string;
-  status: 'in-progress' | 'completed' | 'failed';
-  createdAt: Date;
-  completedAt: Date | null;
-  costUsd: number;
-}
-
-function formatDuration(ms: number): string {
-  const seconds = Math.floor(ms / 1000);
-  const minutes = Math.floor(seconds / 60);
-  const hours = Math.floor(minutes / 60);
-
-  if (hours > 0) {
-    return `${hours}h ${minutes % 60}m`;
-  }
-  if (minutes > 0) {
-    return `${minutes}m`;
-  }
-  return `${seconds}s`;
-}
-
-function getStatusDisplay(status: string): string {
-  return status;
-}
-
-function truncate(str: string, maxLen: number): string {
-  if (str.length <= maxLen) return str;
-  return `${str.slice(0, maxLen - 1)}\u2026`;
-}
-
-async function listWorkspaces(): Promise<void> {
-  const workspacesDir = process.env.WORKSPACES_DIR || DEFAULT_WORKSPACES_DIR;
-
-  let entries: string[];
-  try {
-    entries = await fs.readdir(workspacesDir);
-  } catch {
-    console.log('No workspaces directory found.');
-    console.log(`Expected: ${workspacesDir}`);
-    return;
-  }
-
-  const workspaces: WorkspaceInfo[] = [];
-
-  for (const entry of entries) {
-    const sessionPath = resolveSessionJsonPath(path.join(workspacesDir, entry));
-    try {
-      const content = await fs.readFile(sessionPath, 'utf8');
-      const data = JSON.parse(content) as SessionJson;
-
-      workspaces.push({
-        name: entry,
-        url: data.session.webUrl,
-        status: data.session.status,
-        createdAt: new Date(data.session.createdAt),
-        completedAt: data.session.completedAt ? new Date(data.session.completedAt) : null,
-        costUsd: data.metrics.total_cost_usd,
-      });
-    } catch {
-      // Skip directories without valid session.json
-    }
-  }
-
-  if (workspaces.length === 0) {
-    console.log('\nNo workspaces found.');
-    console.log('Run a pipeline first: ./shannon start -u <url> -r <repo>');
-    return;
-  }
-
-  // Sort by creation date (most recent first)
-  workspaces.sort((a, b) => b.createdAt.getTime() - a.createdAt.getTime());
-
-  console.log('\n=== Shannon Workspaces ===\n');
-
-  // Column widths
-  const nameWidth = 30;
-  const urlWidth = 30;
-  const statusWidth = 14;
-  const durationWidth = 10;
-  const costWidth = 10;
-
-  // Header
-  console.log(
-    '  ' +
-      'WORKSPACE'.padEnd(nameWidth) +
-      'URL'.padEnd(urlWidth) +
-      'STATUS'.padEnd(statusWidth) +
-      'DURATION'.padEnd(durationWidth) +
-      'COST'.padEnd(costWidth),
-  );
-  console.log(`  ${'\u2500'.repeat(nameWidth + urlWidth + statusWidth + durationWidth + costWidth)}`);
-
-  let resumableCount = 0;
-
-  for (const ws of workspaces) {
-    const now = new Date();
-    const endTime = ws.completedAt || now;
-    const durationMs = endTime.getTime() - ws.createdAt.getTime();
-    const duration = formatDuration(durationMs);
-    const cost = `$${ws.costUsd.toFixed(2)}`;
-    const isResumable = ws.status !== 'completed';
-
-    if (isResumable) {
-      resumableCount++;
-    }
-
-    const resumeTag = isResumable ? ' (resumable)' : '';
-
-    console.log(
-      '  ' +
-        truncate(ws.name, nameWidth - 2).padEnd(nameWidth) +
-        truncate(ws.url, urlWidth - 2).padEnd(urlWidth) +
-        getStatusDisplay(ws.status).padEnd(statusWidth) +
-        duration.padEnd(durationWidth) +
-        cost.padEnd(costWidth) +
-        resumeTag,
-    );
-  }
-
-  console.log();
-  const summary = `${workspaces.length} workspace${workspaces.length === 1 ? '' : 's'} found`;
-  const resumeSummary = resumableCount > 0 ? ` (${resumableCount} resumable)` : '';
-  console.log(`${summary}${resumeSummary}`);
-
-  if (resumableCount > 0) {
-    console.log('\nResume with: ./shannon start -u <url> -r <repo> -w <name>');
-  }
-
-  console.log();
-}
-
-listWorkspaces().catch((err) => {
-  console.error('Error listing workspaces:', err);
-  process.exit(1);
-});

apps/worker/src/types/config.ts

@@ -11,7 +11,7 @@
 export type RuleType = 'url_path' | 'subdomain' | 'domain' | 'method' | 'header' | 'parameter' | 'code_path';
 
 export interface Rule {
-  description: string;
+  description?: string;
   type: RuleType;
   value: string;
 }

apps/worker/templates/typst/report.typ

@@ -0,0 +1,535 @@
+// =============================================================================
+// Security Assessment Report — Typst template
+// Invoke:
+//   typst compile --root <root> --input data=/data.json report.typ out.pdf
+// Optional overrides:
+//   --input tester=<name>  --input brand=<name>
+// =============================================================================
+
+#let data = json(sys.inputs.data)
+
+// Top-level discriminator. Schema variants in report-output-schema.ts:
+//   exploits → ExploitsReportData (exploit=true runs, full reproduction)
+//   findings → FindingsReportData (exploit=false runs, analysis-only)
+#let mode = data.at("mode", default: "exploits")
+
+#let tester-override = sys.inputs.at("tester", default: "Shannon")
+#let brand = sys.inputs.at("brand", default: "Shannon | AI Pentester by Keygraph")
+
+// ---------- Palette ---------------------------------------------------------
+// Kept distinct so Critical / High are not confused under monitor gamma.
+#let sev-color(level) = {
+  if level == "Critical" { rgb("#DC2626") }        // red-600
+  else if level == "High" { rgb("#EA580C") }       // orange-600
+  else if level == "Medium" { rgb("#D97706") }     // amber-600
+  else if level == "Low" { rgb("#2563EB") }        // blue-600
+  else { rgb("#6B7280") }
+}
+
+#let confidence-color(c) = {
+  if c == "High" { rgb("#15803D") }    // green-700
+  else if c == "Medium" { rgb("#D97706") } // amber-600
+  else if c == "Low" { rgb("#6B7280") }   // gray-500
+  else { rgb("#6B7280") }
+}
+
+// Warm, editorial, high-contrast document palette.
+#let ink = rgb("#141414")          // warm near-black text
+#let muted = rgb("#5C5850")        // warm gray-brown labels
+#let tertiary = rgb("#9A958D")     // lightest muted
+#let rule = rgb("#E6E1D9")         // warm hair rules
+#let rule-soft = rgb("#D9D3CA")
+#let code-bg = rgb("#F6F1EB")      // warm eggshell
+#let alt-bg = rgb("#EBE6DF")
+#let page-bg = white
+
+// ---------- Page setup ------------------------------------------------------
+#set document(title: "Security Assessment Report", author: brand)
+
+#set page(
+  paper: "a4",
+  margin: (top: 2.2cm, bottom: 2.2cm, left: 2.2cm, right: 2.2cm),
+  fill: page-bg,
+  header: context {
+    if counter(page).get().first() > 1 [
+      #set text(size: 8.5pt, fill: muted)
+      #grid(columns: (1fr, auto),
+        [Security Assessment Report],
+        [CONFIDENTIAL],
+      )
+      #v(-4pt)
+      #line(length: 100%, stroke: 0.3pt + rule)
+    ]
+  },
+  footer: context {
+    if counter(page).get().first() > 1 [
+      #set text(size: 8.5pt, fill: muted)
+      #line(length: 100%, stroke: 0.3pt + rule)
+      #v(2pt)
+      #grid(columns: (1fr, auto),
+        [#data.meta.assessmentDate],
+        [#counter(page).display() / #context counter(page).final().first()],
+      )
+    ]
+  },
+)
+
+#set text(size: 10.5pt, fill: ink)
+#set par(leading: 0.7em, justify: false)
+
+#show heading.where(level: 1): it => [
+  #pagebreak(weak: true)
+  #v(4pt)
+  #set text(size: 24pt, weight: "bold", fill: ink)
+  #it.body
+  #v(4pt)
+  #line(length: 100%, stroke: 0.4pt + rule)
+  #v(10pt)
+]
+#show heading.where(level: 2): it => [
+  #v(10pt)
+  #set text(size: 14pt, weight: "semibold", fill: ink)
+  #it.body
+  #v(2pt)
+]
+#show heading.where(level: 3): it => [
+  #v(8pt)
+  #set text(size: 11.5pt, weight: "semibold", fill: ink)
+  #it.body
+  #v(-2pt)
+]
+
+#show raw: set text(size: 8.5pt)
+#show raw.where(block: false): it => box(
+  fill: code-bg,
+  inset: (x: 3pt, y: 0pt),
+  outset: (y: 2pt),
+  radius: 2pt,
+  it,
+)
+#show raw.where(block: true): it => block(
+  fill: code-bg,
+  stroke: (left: 2pt + rule, rest: none),
+  inset: (x: 10pt, y: 8pt),
+  width: 100%,
+  breakable: true,
+  {
+    set par(leading: 0.5em, justify: false)
+    it
+  },
+)
+
+// ---------- Helpers ---------------------------------------------------------
+#let chip(label, color) = box(
+  fill: color,
+  inset: (x: 6pt, y: 2pt),
+  radius: 2pt,
+  text(fill: white, weight: "bold", size: 7.5pt, tracking: 0.3pt, upper(label)),
+)
+
+#let categories-in-order = (
+  "Authentication",
+  "Authorization",
+  "XSS",
+  "Injection",
+  "SSRF",
+  "Other",
+)
+
+#let sev-chip(level) = chip(level, sev-color(level))
+#let confidence-chip(c) = chip(c + " confidence", confidence-color(c))
+
+// inline-code renders a string, turning backtick-wrapped spans into
+// inline raw. Safe on odd counts — a trailing unclosed backtick is
+// emitted as literal text so nothing gets swallowed.
+#let inline-code(s) = {
+  if type(s) != str { return s }
+  let parts = s.split("`")
+  if parts.len() == 1 { return parts.at(0) }
+  let out = []
+  for (i, p) in parts.enumerate() {
+    if calc.even(i) {
+      out += [#p]
+    } else if i == parts.len() - 1 {
+      out += [#("`" + p)]
+    } else {
+      out += raw(p)
+    }
+  }
+  out
+}
+
+#let render-items(items) = {
+  for item in items {
+    if item.kind == "prose" [
+      #par(inline-code(item.text))
+    ] else if item.kind == "code" [
+      #raw(item.block.content, lang: item.block.language, block: true)
+    ]
+  }
+}
+
+// Render step items as a bulleted list; prose items become bullets,
+// code items break the list and render as code blocks in between.
+#let render-bulleted-items(items) = {
+  for item in items {
+    if item.kind == "prose" [
+      - #inline-code(item.text)
+    ] else if item.kind == "code" [
+      #raw(item.block.content, lang: item.block.language, block: true)
+    ]
+  }
+}
+
+// Render step items as a numbered list; prose items become enumerated,
+// code items break the list and render as code blocks in between.
+#let render-numbered-items(items) = {
+  for item in items {
+    if item.kind == "prose" [
+      + #inline-code(item.text)
+    ] else if item.kind == "code" [
+      #raw(item.block.content, lang: item.block.language, block: true)
+    ]
+  }
+}
+
+// Render an array of strings as a bulleted list with inline-code support.
+#let code-list(items) = list(..items.map(inline-code))
+
+#let kv(label, value) = grid(
+  columns: (auto, 1fr),
+  column-gutter: 14pt,
+  row-gutter: 4pt,
+  text(fill: muted, size: 9.5pt)[#label],
+  value,
+)
+
+// ---------- COVER PAGE ------------------------------------------------------
+#page(header: none, footer: none)[
+  #set align(left)
+  #v(3.2cm)
+
+  #let brand-parts = brand.split("|").map(p => p.trim())
+  #grid(
+    columns: (auto, 1fr),
+    column-gutter: 8pt,
+    align: (horizon, horizon),
+    image("/assets/keygraph-logo.png", width: 1.6cm),
+    {
+      set par(leading: 0.6em)
+      text(size: 11pt, fill: ink, weight: "semibold", tracking: 1.2pt)[
+        #upper(brand-parts.at(0))
+      ]
+      if brand-parts.len() > 1 {
+        linebreak()
+        text(size: 9pt, fill: muted, weight: "regular")[
+          #brand-parts.slice(1).join(" ")
+        ]
+      }
+    }
+  )
+  #set par(leading: 0.7em)
+
+  #v(1.6cm)
+  #set par(leading: 0.4em)
+  #text(size: 46pt, weight: "bold", fill: ink)[
+    Security\
+    Assessment\
+    Report
+  ]
+  #set par(leading: 0.7em)
+
+  #v(1fr)
+
+  #line(length: 100%, stroke: 0.3pt + rule)
+  #v(0.6cm)
+
+  #grid(
+    columns: (1fr, 1fr),
+    column-gutter: 28pt,
+    row-gutter: 14pt,
+    grid(
+      columns: (auto, 1fr),
+      column-gutter: 18pt,
+      row-gutter: 14pt,
+      text(fill: muted, size: 9pt)[Target],      text(size: 10pt)[#inline-code(data.meta.target)],
+      text(fill: muted, size: 9pt)[Date],        text(size: 10pt)[#data.meta.assessmentDate],
+      ..(if "application" in data.meta and data.meta.application != none {
+        (text(fill: muted, size: 9pt)[Application], text(size: 10pt)[#inline-code(data.meta.application)])
+      } else { () }),
+    ),
+    grid(
+      columns: (auto, 1fr),
+      column-gutter: 18pt,
+      row-gutter: 14pt,
+      text(fill: muted, size: 9pt)[Tester],         text(size: 10pt)[#tester-override],
+      text(fill: muted, size: 9pt)[Classification],
+        text(size: 10pt, weight: "semibold")[#data.meta.classification],
+    ),
+  )
+
+  #v(0.8cm)
+  #text(size: 8pt, fill: muted)[
+    This document contains sensitive security findings.
+    Handle in accordance with your organization's data classification policy.
+  ]
+]
+
+// ---------- TABLE OF CONTENTS -----------------------------------------------
+#outline(title: [Contents], depth: 3, indent: auto)
+
+// ---------- EXECUTIVE SUMMARY -----------------------------------------------
+= Executive Summary
+
+#grid(
+  columns: (auto, 1fr),
+  column-gutter: 20pt,
+  row-gutter: 12pt,
+  text(fill: muted, size: 10pt)[Target],       text(size: 10.5pt)[#inline-code(data.meta.target)],
+  text(fill: muted, size: 10pt)[Date],         text(size: 10.5pt)[#data.meta.assessmentDate],
+  ..(if "application" in data.meta and data.meta.application != none {
+    (text(fill: muted, size: 10pt)[Application], text(size: 10.5pt)[#inline-code(data.meta.application)])
+  } else { () }),
+  text(fill: muted, size: 10pt)[Tester],       text(size: 10.5pt)[#tester-override],
+)
+
+== Scope
+
+#inline-code(data.scope)
+
+// ---------- BY TYPE ---------------------------------------------------------
+#let by-type-entries = if mode == "exploits" { data.exploitedByType } else { data.identifiedByType }
+#if mode == "exploits" [
+  = Successfully Exploited Vulnerabilities by Type
+] else [
+  = Identified Vulnerabilities by Type
+]
+
+#for entry in by-type-entries [
+  == #entry.category
+  #if "narrative" in entry and entry.narrative != none [
+    #inline-code(entry.narrative)
+  ]
+  #if "bullets" in entry and entry.bullets != none [
+    #list(
+      ..entry.bullets.map(b => [
+        #text(weight: "semibold")[#b.id] — #inline-code(b.description)
+      ])
+    )
+  ]
+]
+
+// ---------- SUMMARY ---------------------------------------------------------
+= Summary
+
+#let s = data.summary
+#let sev = data.derivedCounts.bySeverity
+
+#let severity-card(label, sev-key, n) = box(
+  fill: sev-color(sev-key),
+  inset: (x: 8pt, y: 12pt),
+  radius: 4pt,
+  width: 100%,
+  stack(
+    dir: ttb,
+    spacing: 6pt,
+    text(fill: white, weight: "bold", size: 20pt)[#n],
+    text(fill: white, size: 8pt, tracking: 0.5pt)[#upper(label)],
+  ),
+)
+
+#grid(
+  columns: 4,
+  column-gutter: 8pt,
+  severity-card("Critical", "Critical", sev.Critical),
+  severity-card("High", "High", sev.High),
+  severity-card("Medium", "Medium", sev.Medium),
+  severity-card("Low", "Low", sev.Low),
+)
+
+#if mode == "findings" [
+  #v(18pt)
+  #let cf = data.derivedCounts.byConfidence
+  #let confidence-card(label, c-key, n) = box(
+    stroke: 0.6pt + confidence-color(c-key),
+    inset: (x: 8pt, y: 12pt),
+    radius: 4pt,
+    width: 100%,
+    stack(
+      dir: ttb,
+      spacing: 6pt,
+      text(fill: ink, weight: "bold", size: 20pt)[#n],
+      text(fill: confidence-color(c-key), size: 8pt, tracking: 0.5pt)[#upper(label + " confidence")],
+    ),
+  )
+
+  #grid(
+    columns: 3,
+    column-gutter: 8pt,
+    confidence-card("High", "High", cf.High),
+    confidence-card("Medium", "Medium", cf.Medium),
+    confidence-card("Low", "Low", cf.Low),
+  )
+]
+
+#v(14pt)
+
+#if mode == "exploits" [
+  #grid(
+    columns: (auto, 1fr),
+    column-gutter: 14pt,
+    row-gutter: 4pt,
+    text(fill: muted, size: 10pt)[Total identified],
+    text(weight: "semibold")[#s.totalIdentified],
+    text(fill: muted, size: 10pt)[Successfully exploited],
+    text(weight: "semibold")[#s.successfullyExploited],
+  )
+] else [
+  #grid(
+    columns: (auto, 1fr),
+    column-gutter: 14pt,
+    row-gutter: 4pt,
+    text(fill: muted, size: 10pt)[Total identified],
+    text(weight: "semibold")[#s.totalIdentified],
+  )
+]
+
+#v(8pt)
+
+#let breakdown = if mode == "exploits" { s.exploitedBreakdown } else { s.identifiedBreakdown }
+#list(
+  ..breakdown.map(c => [
+    #text(weight: "semibold")[#c.count] #c.category#if "note" in c and c.note != none [ — #inline-code(c.note)]
+  ])
+)
+
+#if mode == "exploits" [
+  #if "outOfScope" in s and s.outOfScope != none [
+    #v(4pt)
+    #text(weight: "semibold")[Out of Scope#if "note" in s.outOfScope and s.outOfScope.note != none [ (#s.outOfScope.note)]:] #s.outOfScope.total vulnerabilities
+    #if "breakdown" in s.outOfScope and s.outOfScope.breakdown != none [
+      #list(
+        ..s.outOfScope.breakdown.map(c => [
+          #text(weight: "semibold")[#c.count] #c.category#if "note" in c and c.note != none [ — #inline-code(c.note)]
+        ])
+      )
+    ]
+  ]
+
+  #if "blockedByConstraints" in s and s.blockedByConstraints != none [
+    #v(4pt)
+    #text(weight: "semibold")[Blocked by Testing Constraints:] #s.blockedByConstraints.total#if "note" in s.blockedByConstraints and s.blockedByConstraints.note != none [ — #s.blockedByConstraints.note]
+  ]
+]
+
+== Critical Findings
+
+#enum(..s.criticalFindings.map(f => [#inline-code(f)]))
+
+// ---------- FINDINGS OVERVIEW -----------------------------------------------
+= Findings Overview
+
+#let show-confidence-col = mode == "findings"
+
+#table(
+  columns: if show-confidence-col { (auto, 1fr, auto, auto, auto) } else { (auto, 1fr, auto, auto) },
+  stroke: none,
+  inset: (x: 8pt, y: 7pt),
+  align: if show-confidence-col { (left, left, left, center, center) } else { (left, left, left, center) },
+  fill: (_, row) => if row == 0 { none } else if calc.even(row) { code-bg } else { none },
+  table.header(
+    text(size: 9.5pt, weight: "semibold")[ID],
+    text(size: 9.5pt, weight: "semibold")[Title],
+    text(size: 9.5pt, weight: "semibold")[Category],
+    text(size: 9.5pt, weight: "semibold")[Severity],
+    ..(if show-confidence-col { (text(size: 9.5pt, weight: "semibold")[Confidence],) } else { () }),
+  ),
+  ..data.findings.map(f => (
+    text(weight: "semibold")[#f.id],
+    inline-code(f.title),
+    text(size: 9.5pt)[#f.category],
+    sev-chip(f.severity),
+    ..(if show-confidence-col { (confidence-chip(f.confidence),) } else { () }),
+  )).flatten()
+)
+
+// ---------- FINDING RENDER --------------------------------------------------
+#let render-finding-summary(f) = [
+  #v(8pt)
+  #grid(
+    columns: (auto, 1fr),
+    column-gutter: 18pt,
+    row-gutter: 12pt,
+    text(fill: muted, size: 9.5pt)[Location], text(size: 10pt)[#inline-code(f.summary.vulnerableLocation)],
+    text(fill: muted, size: 9.5pt)[Overview], text(size: 10pt)[#inline-code(f.summary.overview)],
+    text(fill: muted, size: 9.5pt)[Impact],   text(size: 10pt)[#inline-code(f.summary.impact)],
+  )
+]
+
+#let render-finding-extras(f) = [
+  #if "notes" in f and f.notes != none and f.notes.len() > 0 [
+    #heading(level: 3, outlined: false)[Notes]
+    #render-bulleted-items(f.notes)
+  ]
+
+  #if "additionalSections" in f and f.additionalSections != none [
+    #for extra in f.additionalSections [
+      #heading(level: 3, outlined: false)[#inline-code(extra.heading)]
+      #render-items(extra.items)
+    ]
+  ]
+]
+
+#let render-exploit(f) = [
+  == #f.id: #inline-code(f.title)
+  #sev-chip(f.severity)
+
+  #render-finding-summary(f)
+
+  === Prerequisites
+  #inline-code(f.prerequisites)
+
+  === Exploitation Steps
+  #for step in f.exploitationSteps [
+    #text(weight: "semibold")[Step #step.number#if "title" in step and step.title != none [ — #inline-code(step.title)]]
+
+    #render-items(step.items)
+  ]
+
+  === Proof of Impact
+  #render-numbered-items(f.proofOfImpact)
+
+  #render-finding-extras(f)
+
+  #v(16pt)
+]
+
+#let render-analysis(f) = [
+  == #f.id: #inline-code(f.title)
+  #sev-chip(f.severity) #h(4pt) #confidence-chip(f.confidence)
+
+  #render-finding-summary(f)
+
+  #render-finding-extras(f)
+
+  #v(16pt)
+]
+
+#let render-finding(f) = if mode == "exploits" { render-exploit(f) } else { render-analysis(f) }
+
+// ---------- PER-CATEGORY -----------------------------------------------------
+#let category-section-label(n) = if mode == "exploits" {
+  "Exploitation Evidence"
+} else {
+  "Findings"
+}
+
+#for cat in categories-in-order {
+  let cat-findings = data.findings.filter(f => f.category == cat)
+  if cat-findings.len() > 0 [
+    = #cat #category-section-label(cat-findings.len()) (#cat-findings.len() #if cat-findings.len() == 1 [finding] else [findings])
+    #for f in cat-findings {
+      render-finding(f)
+    }
+  ]
+}

docs/ai-providers.md

@@ -12,17 +12,29 @@ The provider half decides where the request goes, which credential is used, and
 
 | Provider | Value | Credential |
 | --- | --- | --- |
-| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` |
-| OpenAI | `openai` | `OPENAI_API_KEY` |
-| xAI | `xai` | `XAI_API_KEY` |
+| Anthropic | `anthropic` | `SHANNON_AI_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) |
+| OpenAI | `openai` | `SHANNON_AI_API_KEY` |
+| xAI | `xai` | `SHANNON_AI_API_KEY` |
 | AWS Bedrock | `amazon-bedrock` | `AWS_REGION` and `AWS_BEARER_TOKEN_BEDROCK` |
 
-Shannon does not invent credential names — each is the variable that provider's own tooling already uses. If `SHANNON_AI_MODEL` is unset, Shannon uses `anthropic:claude-sonnet-4-6`.
+`SHANNON_AI_API_KEY` holds the key for whichever provider `SHANNON_AI_MODEL` names. Bedrock is the exception — it authenticates through its `AWS_` variables only. If `SHANNON_AI_MODEL` is unset, Shannon uses `anthropic:claude-sonnet-4-6`.
+
+Anthropic, OpenAI, and xAI also accept their native variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`); if one of those is set, it is used instead of `SHANNON_AI_API_KEY`.
 
 Shannon forwards only the selected provider's credential into the scan container. Keys for other providers stay on your machine.
 
-> [!NOTE]
-> Only the **first** colon separates the provider from the model ID, so Bedrock IDs that contain colons work unchanged: `amazon-bedrock:us.anthropic.claude-opus-4-5-20251101-v1:0`.
+### Any other provider
+
+Shannon accepts any provider and model present in the Pi harness catalogue. Browse them at [pi.dev/models](https://pi.dev/models). These are technically supported but not recommended. Claude models are best-supported (see the note below).
+
+```bash
+export SHANNON_AI_API_KEY=your-api-key                 # the provider's API key
+export SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3  # <provider>:<model-id>
+```
+
+This path covers providers whose credential is a single API key. Providers that need more than that are not currently supported.
+
+`npx @keygraph/shannon setup` exposes this as the **Other provider** option.
 
 > [!IMPORTANT]
 > Claude models are the best-supported option. Shannon's evaluations, internal testing, and agent harness are tuned for Claude. Other models are permitted and validated against the harness catalogue, but may not follow Shannon's instructions or tool-use constraints as reliably. Use them at your own risk.
@@ -58,21 +70,21 @@ The pattern is learned once: export the provider's key, name the model. Two line
 Anthropic (default):
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+export SHANNON_AI_API_KEY=sk-ant-...
 export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 ```
 
 OpenAI:
 
 ```bash
-export OPENAI_API_KEY=sk-...
+export SHANNON_AI_API_KEY=sk-...
 export SHANNON_AI_MODEL=openai:gpt-5.6-sol
 ```
 
 xAI:
 
 ```bash
-export XAI_API_KEY=xai-...
+export SHANNON_AI_API_KEY=xai-...
 export SHANNON_AI_MODEL=xai:grok-4.5
 ```
 
@@ -96,16 +108,16 @@ To route model traffic through your own infrastructure — a corporate proxy, an
 
 | Gateway serves | Model prefix | API key |
 | --- | --- | --- |
-| Anthropic Messages | `anthropic:` | `ANTHROPIC_API_KEY` |
-| OpenAI Chat Completions | `openai:` | `OPENAI_API_KEY` |
-| OpenAI Responses | `openai:` + `SHANNON_AI_OPENAI_FORMAT=responses` | `OPENAI_API_KEY` |
+| Anthropic Messages | `anthropic:` | `SHANNON_AI_API_KEY` |
+| OpenAI Chat Completions | `openai:` | `SHANNON_AI_API_KEY` |
+| OpenAI Responses | `openai:` + `SHANNON_AI_OPENAI_FORMAT=responses` | `SHANNON_AI_API_KEY` |
 
 The model ID is whatever name your gateway serves it under; it does not have to exist in Shannon's catalogue.
 
 Anthropic Messages:
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+export SHANNON_AI_API_KEY=sk-ant-...
 export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 export SHANNON_AI_BASE_URL=https://llm-gateway.example.com
 ```
@@ -113,7 +125,7 @@ export SHANNON_AI_BASE_URL=https://llm-gateway.example.com
 OpenAI Chat Completions:
 
 ```bash
-export OPENAI_API_KEY=sk-...
+export SHANNON_AI_API_KEY=sk-...
 export SHANNON_AI_MODEL=openai:gpt-5.6-sol
 export SHANNON_AI_BASE_URL=https://llm-gateway.example.com/v1
 ```
@@ -132,13 +144,55 @@ The variable is rejected in preflight where it cannot take effect: with a non-`o
 
 `npx @keygraph/shannon setup` covers this under **Custom Base URL**, which asks which API your gateway serves and configures the matching provider for you.
 
+## OpenAI Codex (ChatGPT Plus/Pro subscription)
+
+A ChatGPT Plus or Pro Codex subscription can run Shannon. Shannon reuses a login created by Pi.
+
+Before running a pentest, review the [cyber safeguards requirements](#cyber-safeguards-do-this-before-your-first-scan).
+
+1. Install Pi by following the instructions at [pi.dev](https://pi.dev).
+2. Log in with your subscription using Pi's [subscription authentication guide](https://pi.dev/docs/latest/providers#subscriptions). This creates `~/.pi/agent/auth.json` with an `openai-codex` entry.
+
+3. Select a Codex model and enable Pi authentication:
+
+   ```bash
+   export SHANNON_USE_PI_AUTH=1
+   export SHANNON_AI_MODEL=openai-codex:gpt-5.5
+   ```
+
+4. In npx mode, run `npx @keygraph/shannon start ...` from the same shell. In source-build mode, add the two variables to `.env` and run `./shannon start ...`.
+
+Supported Codex models are `gpt-5.6-sol`, `gpt-5.5`, and `gpt-5.4`.
+
+## Claude Code subscription
+
+The latest version of Shannon does not support Claude Code subscriptions. The [`shannon-v1`](https://github.com/KeygraphHQ/shannon/tree/shannon-v1) branch is the final release built on the Claude Agent SDK and supports Claude Code OAuth.
+
+Before running a pentest, review the [cyber safeguards requirements](#cyber-safeguards-do-this-before-your-first-scan).
+
+1. Generate a Claude Code OAuth token:
+
+   ```bash
+   claude setup-token
+   ```
+
+2. Run the setup flow for the final `shannon-v1` release:
+
+   ```bash
+   npx @keygraph/shannon@1.9.0 setup
+   ```
+
+3. Select **OAuth Token** and enter the token generated by Claude Code.
+4. Start the pentest with `npx @keygraph/shannon@1.9.0 start ...`.
+
+These instructions apply only to `shannon-v1`.
+
 ## Validation
 
 Checks run before a scan starts, so mistakes fail immediately rather than partway through a run:
 
-- **Provider** — always validated against the providers Shannon's harness knows. An unrecognised provider is rejected with the valid list.
-- **Model ID** — validated against the harness catalogue for that provider, so a typo is caught instantly.
-- **Credential presence** — always validated for the selected provider.
+- **Provider and model ID** — validated against the Pi harness catalogue. An unknown provider or model ID fails preflight with a pointer to [pi.dev/models](https://pi.dev/models). A custom base URL exempts the model ID, since a gateway may serve its own names.
+- **Credential presence** — validated for the selected provider, or read from Pi when `SHANNON_USE_PI_AUTH=1`.
 - **Credential validity** — one minimal request against the model the scan will use, so a rejected key, an exhausted quota, or a model the account cannot reach fails before any agent runs. Bedrock included: its bearer token and region go through the same probe.
 
 ## Migrating from the three-tier configuration

docs/configuration.md

@@ -115,7 +115,7 @@ A finding carries one rating or the other, never both: an exploited finding is r
 
 ### SARIF Output
 
-Set `sarif: "true"` to write `report.sarif` next to `Security-Assessment-Report.md` at the workspace root, for upload to GitHub code scanning or any other SARIF consumer.
+Set `sarif: "true"` to write `report.sarif` next to `Security-Assessment-Report.pdf` at the workspace root, for upload to GitHub code scanning or any other SARIF consumer.
 
 ```yaml
 exploit: "true"

docs/development.md

@@ -58,7 +58,8 @@ Monitor progress:
 
 ```bash
 npx @keygraph/shannon logs <workspace>
-npx @keygraph/shannon status
+npx @keygraph/shannon status <workspace>
+npx @keygraph/shannon scans
 npx @keygraph/shannon version
 ```
 
@@ -66,7 +67,8 @@ Source-build equivalents:
 
 ```bash
 ./shannon logs <workspace>
-./shannon status
+./shannon status <workspace>
+./shannon scans
 ./shannon version
 ```
 
@@ -79,16 +81,17 @@ open http://localhost:8233
 Stop Shannon:
 
 ```bash
-npx @keygraph/shannon stop
-npx @keygraph/shannon stop --clean       # confirms first; add --yes (or -y) to skip
-npx @keygraph/shannon uninstall          # confirms first; add --yes (or -y) to skip
+npx @keygraph/shannon stop <workspace>   # stop one scan (confirms first; add --yes/-y to skip)
+npx @keygraph/shannon stop --all         # stop all scans (Temporal stays up)
+npx @keygraph/shannon reset              # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
 
 Source-build equivalents:
 
 ```bash
-./shannon stop
-./shannon stop --clean                   # add --yes (or -y) to skip the confirmation
+./shannon stop <workspace>               # stop one scan (confirms first; add --yes/-y to skip)
+./shannon stop --all                     # stop all scans (Temporal stays up)
+./shannon reset                          # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
 
 Usage examples:
@@ -106,8 +109,11 @@ npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-repo
 # Named workspace.
 npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit
 
-# List all workspaces.
-npx @keygraph/shannon workspaces
+# Stream the log until the scan finishes, then exit on its outcome (useful in CI).
+npx @keygraph/shannon start -u https://example.com -r /path/to/repo --follow
+
+# List completed scans.
+npx @keygraph/shannon scans
 ```
 
 Source-build examples:
@@ -117,7 +123,8 @@ Source-build examples:
 ./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml
 ./shannon start -u https://example.com -r /path/to/repo -o ./my-reports
 ./shannon start -u https://example.com -r /path/to/repo -w q1-audit
-./shannon workspaces
+./shannon start -u https://example.com -r /path/to/repo --follow
+./shannon scans
 
 # Rebuild the worker image.
 ./shannon build --no-cache
@@ -132,11 +139,12 @@ Results are saved to the workspaces directory:
 
 Use `-o <path>` to copy deliverables to a custom output directory after a run completes.
 
-Output structure — the run directory's top level holds only the final report; everything else is nested under a hidden `.shannon/` directory:
+Output structure — the run directory's top level holds the final report, in PDF and Markdown; everything else is nested under a hidden `.shannon/` directory:
 
 ```text
 workspaces/{hostname}_{sessionId}/
-|-- Security-Assessment-Report.md   # the final report (the deliverable)
+|-- Security-Assessment-Report.pdf  # the final report (PDF)
+|-- Security-Assessment-Report.md   # the final report (Markdown)
 `-- .shannon/                       # internals
     |-- deliverables/               # report source, per-phase analysis, queues
     |-- agents/                     # per-agent logs

docs/workspaces.md

@@ -11,7 +11,7 @@ Shannon uses workspaces to store scan state, logs, prompts, and deliverables. Wo
 - Use `-w <name>` to give a run a custom name.
 - To resume a run, pass the same workspace name with `-w`.
 - Each agent's progress is checkpointed so resumed runs can skip completed work.
-- The final report is surfaced at the workspace root as `Security-Assessment-Report.md`. Run internals — deliverables, logs, prompts, and session state — live under a hidden `.shannon/` directory.
+- The final report is surfaced at the workspace root as `Security-Assessment-Report.pdf` and `Security-Assessment-Report.md`. Run internals — deliverables, logs, prompts, and session state — live under a hidden `.shannon/` directory.
 
 > [!NOTE]
 > The URL must match the original workspace URL when resuming. Shannon rejects mismatched URLs to prevent cross-target contamination.
@@ -36,10 +36,10 @@ Resume an auto-named workspace:
 npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808
 ```
 
-List all workspaces:
+List completed scans:
 
 ```bash
-npx @keygraph/shannon workspaces
+npx @keygraph/shannon scans
 ```
 
 Source-build equivalents:
@@ -47,5 +47,5 @@ Source-build equivalents:
 ```bash
 ./shannon start -u https://example.com -r /path/to/repo -w my-audit
 ./shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808
-./shannon workspaces
+./shannon scans
 ```

entrypoint.sh

@@ -12,7 +12,7 @@ if [ -n "$TARGET_UID" ] && [ "$TARGET_UID" != "$CURRENT_UID" ]; then
   groupadd -g "$TARGET_GID" pentest
   useradd -u "$TARGET_UID" -g pentest -s /bin/bash -M pentest
 
-  chown -R pentest:pentest /app/sessions /app/workspaces /tmp/.claude
+  chown -R pentest:pentest /app/sessions /app/workspaces /tmp/.claude /tmp/.pi
 fi
 
 exec su -m pentest -c "exec $*"

llms-full.txt

@@ -82,7 +82,7 @@ Sample penetration test reports from intentionally vulnerable applications, prod
 
 - **Docker**: required for the worker container.
 - **Node.js 18+**: required for the recommended `npx` workflow.
-- **AI provider credentials**: Anthropic, OpenAI, xAI, or AWS Bedrock. Claude models are recommended. Gateway and proxy setups are documented separately.
+- **AI provider credentials**: Anthropic, OpenAI, xAI, or AWS Bedrock - or [any other provider](docs/ai-providers.md#any-other-provider). Claude models are recommended. Gateway and proxy setups are documented separately.
 - **Cyber safeguards cleared with your provider**: Anthropic and OpenAI apply real-time safeguards to cyber-security workloads, which can interrupt a scan mid-run. Complete their guidance for legitimate security testers before your first run - see [AI providers](docs/ai-providers.md#cyber-safeguards-do-this-before-your-first-scan).
 
 ### Run Shannon
@@ -323,7 +323,8 @@ Monitor progress:
 
 ```bash
 npx @keygraph/shannon logs <workspace>
-npx @keygraph/shannon status
+npx @keygraph/shannon status <workspace>
+npx @keygraph/shannon scans
 npx @keygraph/shannon version
 ```
 
@@ -331,7 +332,8 @@ Source-build equivalents:
 
 ```bash
 ./shannon logs <workspace>
-./shannon status
+./shannon status <workspace>
+./shannon scans
 ./shannon version
 ```
 
@@ -344,16 +346,17 @@ open http://localhost:8233
 Stop Shannon:
 
 ```bash
-npx @keygraph/shannon stop
-npx @keygraph/shannon stop --clean       # confirms first; add --yes (or -y) to skip
-npx @keygraph/shannon uninstall          # confirms first; add --yes (or -y) to skip
+npx @keygraph/shannon stop <workspace>   # stop one scan (confirms first; add --yes/-y to skip)
+npx @keygraph/shannon stop --all         # stop all scans (Temporal stays up)
+npx @keygraph/shannon reset              # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
 
 Source-build equivalents:
 
 ```bash
-./shannon stop
-./shannon stop --clean                   # add --yes (or -y) to skip the confirmation
+./shannon stop <workspace>               # stop one scan (confirms first; add --yes/-y to skip)
+./shannon stop --all                     # stop all scans (Temporal stays up)
+./shannon reset                          # stop everything and wipe all Temporal data (type 'confirm' to proceed; cannot be skipped)
 ```
 
 Usage examples:
@@ -371,8 +374,11 @@ npx @keygraph/shannon start -u https://example.com -r /path/to/repo -o ./my-repo
 # Named workspace.
 npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w q1-audit
 
-# List all workspaces.
-npx @keygraph/shannon workspaces
+# Stream the log until the scan finishes, then exit on its outcome (useful in CI).
+npx @keygraph/shannon start -u https://example.com -r /path/to/repo --follow
+
+# List completed scans.
+npx @keygraph/shannon scans
 ```
 
 Source-build examples:
@@ -382,7 +388,8 @@ Source-build examples:
 ./shannon start -u https://example.com -r /path/to/repo -c /path/to/my-config.yaml
 ./shannon start -u https://example.com -r /path/to/repo -o ./my-reports
 ./shannon start -u https://example.com -r /path/to/repo -w q1-audit
-./shannon workspaces
+./shannon start -u https://example.com -r /path/to/repo --follow
+./shannon scans
 
 # Rebuild the worker image.
 ./shannon build --no-cache
@@ -397,11 +404,12 @@ Results are saved to the workspaces directory:
 
 Use `-o <path>` to copy deliverables to a custom output directory after a run completes.
 
-Output structure — the run directory's top level holds only the final report; everything else is nested under a hidden `.shannon/` directory:
+Output structure — the run directory's top level holds the final report, in PDF and Markdown; everything else is nested under a hidden `.shannon/` directory:
 
 ```text
 workspaces/{hostname}_{sessionId}/
-|-- Security-Assessment-Report.md   # the final report (the deliverable)
+|-- Security-Assessment-Report.pdf  # the final report (PDF)
+|-- Security-Assessment-Report.md   # the final report (Markdown)
 `-- .shannon/                       # internals
     |-- deliverables/               # report source, per-phase analysis, queues
     |-- agents/                     # per-agent logs
@@ -532,7 +540,7 @@ A finding carries one rating or the other, never both: an exploited finding is r
 
 ### SARIF Output
 
-Set `sarif: "true"` to write `report.sarif` next to `Security-Assessment-Report.md` at the workspace root, for upload to GitHub code scanning or any other SARIF consumer.
+Set `sarif: "true"` to write `report.sarif` next to `Security-Assessment-Report.pdf` at the workspace root, for upload to GitHub code scanning or any other SARIF consumer.
 
 ```yaml
 exploit: "true"
@@ -592,17 +600,29 @@ The provider half decides where the request goes, which credential is used, and
 
 | Provider | Value | Credential |
 | --- | --- | --- |
-| Anthropic | `anthropic` | `ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` |
-| OpenAI | `openai` | `OPENAI_API_KEY` |
-| xAI | `xai` | `XAI_API_KEY` |
+| Anthropic | `anthropic` | `SHANNON_AI_API_KEY` (or `CLAUDE_CODE_OAUTH_TOKEN`) |
+| OpenAI | `openai` | `SHANNON_AI_API_KEY` |
+| xAI | `xai` | `SHANNON_AI_API_KEY` |
 | AWS Bedrock | `amazon-bedrock` | `AWS_REGION` and `AWS_BEARER_TOKEN_BEDROCK` |
 
-Shannon does not invent credential names — each is the variable that provider's own tooling already uses. If `SHANNON_AI_MODEL` is unset, Shannon uses `anthropic:claude-sonnet-4-6`.
+`SHANNON_AI_API_KEY` holds the key for whichever provider `SHANNON_AI_MODEL` names. Bedrock is the exception — it authenticates through its `AWS_` variables only. If `SHANNON_AI_MODEL` is unset, Shannon uses `anthropic:claude-sonnet-4-6`.
+
+Anthropic, OpenAI, and xAI also accept their native variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `XAI_API_KEY`); if one of those is set, it is used instead of `SHANNON_AI_API_KEY`.
 
 Shannon forwards only the selected provider's credential into the scan container. Keys for other providers stay on your machine.
 
-> [!NOTE]
-> Only the **first** colon separates the provider from the model ID, so Bedrock IDs that contain colons work unchanged: `amazon-bedrock:us.anthropic.claude-opus-4-5-20251101-v1:0`.
+### Any other provider
+
+Shannon accepts any provider and model present in the Pi harness catalogue. Browse them at [pi.dev/models](https://pi.dev/models). These are technically supported but not recommended. Claude models are best-supported (see the note below).
+
+```bash
+export SHANNON_AI_API_KEY=your-api-key                 # the provider's API key
+export SHANNON_AI_MODEL=openrouter:moonshotai/kimi-k3  # <provider>:<model-id>
+```
+
+This path covers providers whose credential is a single API key. Providers that need more than that are not currently supported.
+
+`npx @keygraph/shannon setup` exposes this as the **Other provider** option.
 
 > [!IMPORTANT]
 > Claude models are the best-supported option. Shannon's evaluations, internal testing, and agent harness are tuned for Claude. Other models are permitted and validated against the harness catalogue, but may not follow Shannon's instructions or tool-use constraints as reliably. Use them at your own risk.
@@ -638,21 +658,21 @@ The pattern is learned once: export the provider's key, name the model. Two line
 Anthropic (default):
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+export SHANNON_AI_API_KEY=sk-ant-...
 export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 ```
 
 OpenAI:
 
 ```bash
-export OPENAI_API_KEY=sk-...
+export SHANNON_AI_API_KEY=sk-...
 export SHANNON_AI_MODEL=openai:gpt-5.6-sol
 ```
 
 xAI:
 
 ```bash
-export XAI_API_KEY=xai-...
+export SHANNON_AI_API_KEY=xai-...
 export SHANNON_AI_MODEL=xai:grok-4.5
 ```
 
@@ -676,16 +696,16 @@ To route model traffic through your own infrastructure — a corporate proxy, an
 
 | Gateway serves | Model prefix | API key |
 | --- | --- | --- |
-| Anthropic Messages | `anthropic:` | `ANTHROPIC_API_KEY` |
-| OpenAI Chat Completions | `openai:` | `OPENAI_API_KEY` |
-| OpenAI Responses | `openai:` + `SHANNON_AI_OPENAI_FORMAT=responses` | `OPENAI_API_KEY` |
+| Anthropic Messages | `anthropic:` | `SHANNON_AI_API_KEY` |
+| OpenAI Chat Completions | `openai:` | `SHANNON_AI_API_KEY` |
+| OpenAI Responses | `openai:` + `SHANNON_AI_OPENAI_FORMAT=responses` | `SHANNON_AI_API_KEY` |
 
 The model ID is whatever name your gateway serves it under; it does not have to exist in Shannon's catalogue.
 
 Anthropic Messages:
 
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...
+export SHANNON_AI_API_KEY=sk-ant-...
 export SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 export SHANNON_AI_BASE_URL=https://llm-gateway.example.com
 ```
@@ -693,7 +713,7 @@ export SHANNON_AI_BASE_URL=https://llm-gateway.example.com
 OpenAI Chat Completions:
 
 ```bash
-export OPENAI_API_KEY=sk-...
+export SHANNON_AI_API_KEY=sk-...
 export SHANNON_AI_MODEL=openai:gpt-5.6-sol
 export SHANNON_AI_BASE_URL=https://llm-gateway.example.com/v1
 ```
@@ -716,8 +736,7 @@ The variable is rejected in preflight where it cannot take effect: with a non-`o
 
 Checks run before a scan starts, so mistakes fail immediately rather than partway through a run:
 
-- **Provider** — always validated against the providers Shannon's harness knows. An unrecognised provider is rejected with the valid list.
-- **Model ID** — validated against the harness catalogue for that provider, so a typo is caught instantly.
+- **Provider and model ID** — validated against the Pi harness catalogue. An unknown provider or model ID fails preflight with a pointer to [pi.dev/models](https://pi.dev/models). A custom base URL exempts the model ID, since a gateway may serve its own names.
 - **Credential presence** — always validated for the selected provider.
 - **Credential validity** — one minimal request against the model the scan will use, so a rejected key, an exhausted quota, or a model the account cannot reach fails before any agent runs. Bedrock included: its bearer token and region go through the same probe.
 
@@ -850,7 +869,7 @@ Shannon uses workspaces to store scan state, logs, prompts, and deliverables. Wo
 - Use `-w <name>` to give a run a custom name.
 - To resume a run, pass the same workspace name with `-w`.
 - Each agent's progress is checkpointed so resumed runs can skip completed work.
-- The final report is surfaced at the workspace root as `Security-Assessment-Report.md`. Run internals — deliverables, logs, prompts, and session state — live under a hidden `.shannon/` directory.
+- The final report is surfaced at the workspace root as `Security-Assessment-Report.pdf` and `Security-Assessment-Report.md`. Run internals — deliverables, logs, prompts, and session state — live under a hidden `.shannon/` directory.
 
 > [!NOTE]
 > The URL must match the original workspace URL when resuming. Shannon rejects mismatched URLs to prevent cross-target contamination.
@@ -875,10 +894,10 @@ Resume an auto-named workspace:
 npx @keygraph/shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808
 ```
 
-List all workspaces:
+List completed scans:
 
 ```bash
-npx @keygraph/shannon workspaces
+npx @keygraph/shannon scans
 ```
 
 Source-build equivalents:
@@ -886,7 +905,7 @@ Source-build equivalents:
 ```bash
 ./shannon start -u https://example.com -r /path/to/repo -w my-audit
 ./shannon start -u https://example.com -r /path/to/repo -w example-com_shannon-1771007534808
-./shannon workspaces
+./shannon scans
 ```
 
 ---

llms.txt

@@ -12,8 +12,8 @@ Use this file as the concise entry point for AI agents and LLMs reading this rep
 ## Shannon
 
 - [Development](docs/development.md): Source-build workflow, common CLI commands, repository paths, and output locations.
-- [Configuration](docs/configuration.md): Authenticated testing, login flows, rules of engagement, report filters, credential precedence, adaptive thinking, and rate-limit settings.
-- [AI Providers](docs/ai-providers.md): Anthropic, AWS Bedrock, and custom Anthropic-compatible endpoint setup.
+- [Configuration](docs/configuration.md): Authenticated testing, login flows, rules of engagement, report filters, credential precedence, and rate-limit settings.
+- [AI Providers](docs/ai-providers.md): Anthropic, OpenAI, xAI, AWS Bedrock, any other Pi-supported provider, and custom gateway setup.
 - [Platforms and Networking](docs/platforms.md): Windows/WSL2, Linux, macOS, Docker networking, local applications, and custom hostnames.
 - [Workspaces and Resuming](docs/workspaces.md): Workspace storage, naming, resuming interrupted scans, and examples.
 - [Safety and Limitations](docs/safety.md): Authorized-use requirements, non-production guidance, mutative effects, model caveats, scope limits, cost, and performance.

pnpm-lock.yaml

@@ -26,6 +26,9 @@ importers:
       '@clack/prompts':
         specifier: ^1.1.0
         version: 1.1.0
+      '@temporalio/client':
+        specifier: ^1.11.0
+        version: 1.15.0
       chokidar:
         specifier: ^5.0.0
         version: 5.0.0