docs: add a "Why 'Shannon'?" section to the README

Adds a short naming section under "What is Shannon?", directly after
"Why Shannon Exists", and syncs the same text into llms-full.txt.

Frames pentesting as an information problem, which is the actual link to
Claude Shannon, and closes on the "Hey Claude, run Shannon" line.

Actioned from the Aug 21 Shannon 3.0 launch planning session.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

.env.example

@@ -1,46 +1,60 @@
-# Shannon Environment Configuration
-# Copy this file to .env and fill in your credentials
+# Copy to .env and uncomment one provider block.
+# SHANNON_AI_MODEL is <provider>:<model-id>, split on the first colon.
+# Defaults to anthropic:claude-sonnet-4-6.
 
-# Adaptive thinking is enabled automatically on Opus 4.6/4.7/4.8. Set to false to disable.
-# CLAUDE_ADAPTIVE_THINKING=false
-
-# Shannon forwards your machine's /etc/hosts entries into the worker container. Set to false to disable.
-# SHANNON_FORWARD_HOSTS=false
-
-# =============================================================================
-# OPTION 1: Direct Anthropic
-# =============================================================================
-ANTHROPIC_API_KEY=your-api-key-here
-
-# OR use OAuth token instead
+# --- Anthropic ---------------------------------------------------------------
+SHANNON_AI_API_KEY=your-api-key-here
+SHANNON_AI_MODEL=anthropic:claude-sonnet-4-6
 # CLAUDE_CODE_OAUTH_TOKEN=your-oauth-token-here
 
-# =============================================================================
-# OPTION 2: Custom Base URL (compatible proxies, gateways, etc.)
-# =============================================================================
-# Point the SDK at an alternative Anthropic-compatible endpoint.
-# ANTHROPIC_BASE_URL=https://your-proxy.example.com
-# ANTHROPIC_AUTH_TOKEN=your-auth-token   # Auth token for the custom endpoint
+# --- OpenAI ------------------------------------------------------------------
+# SHANNON_AI_API_KEY=your-api-key-here
+# SHANNON_AI_MODEL=openai:gpt-5.5
 
-# =============================================================================
-# Model Tier Overrides (Anthropic API / OAuth / Custom Base URL / Bedrock)
-# =============================================================================
-# Override which model is used for each tier. Defaults are used if not set.
-# Optional for direct Anthropic and custom base URL modes. Required for Bedrock.
-# ANTHROPIC_SMALL_MODEL=...     # Small tier  (default: claude-haiku-4-5-20251001)
-# ANTHROPIC_MEDIUM_MODEL=...    # Medium tier (default: claude-sonnet-4-6)
-# ANTHROPIC_LARGE_MODEL=...     # Large tier  (default: claude-opus-4-8)
+# --- xAI ---------------------------------------------------------------------
+# SHANNON_AI_API_KEY=your-api-key-here
+# SHANNON_AI_MODEL=xai:grok-4.5
 
-# =============================================================================
-# OPTION 3: AWS Bedrock
-# =============================================================================
-# https://aws.amazon.com/blogs/machine-learning/accelerate-ai-development-with-amazon-bedrock-api-keys/
-# Requires the model tier overrides above to be set with Bedrock-specific model IDs.
-# Example Bedrock model IDs for us-east-1:
-#   ANTHROPIC_SMALL_MODEL=us.anthropic.claude-haiku-4-5-20251001-v1:0
-#   ANTHROPIC_MEDIUM_MODEL=us.anthropic.claude-sonnet-4-6
-#   ANTHROPIC_LARGE_MODEL=us.anthropic.claude-opus-4-8
-
-# CLAUDE_CODE_USE_BEDROCK=1
+# --- AWS Bedrock -------------------------------------------------------------
+# Bearer token only; model must be enabled in your region.
 # AWS_REGION=us-east-1
 # AWS_BEARER_TOKEN_BEDROCK=your-bearer-token
+# SHANNON_AI_MODEL=amazon-bedrock:us.anthropic.claude-opus-4-8
+
+# --- 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; the model id is whatever
+# name your gateway serves it under.
+
+# Anthropic compatible - Anthropic Messages:
+# 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:
+# SHANNON_AI_API_KEY=your-gateway-key-here
+# SHANNON_AI_BASE_URL=https://llm-gateway.example.com/v1
+# SHANNON_AI_MODEL=openai:gpt-5.5
+# SHANNON_AI_OPENAI_FORMAT=responses
+
+# --- 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
+
+# Or the guide below to use an xAI subscription
+# https://github.com/KeygraphHQ/shannon/blob/main/docs/ai-providers.md#xai-grok-subscription
+# SHANNON_USE_PI_AUTH=1
+# SHANNON_AI_MODEL=xai:grok-4.6

.github/ISSUE_TEMPLATE/bug_report.yml

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

.github/workflows/release-beta.yml

@@ -189,8 +189,6 @@ jobs:
 
       - name: Publish npm package
         working-directory: apps/cli
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           if npm view "@keygraph/shannon@${{ needs.preflight.outputs.version }}" version 2>/dev/null; then
             echo "Version already published, skipping"

.github/workflows/release.yml

@@ -201,8 +201,6 @@ jobs:
 
       - name: Publish npm package
         working-directory: apps/cli
-        env:
-          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           if npm view "@keygraph/shannon@${{ needs.preflight.outputs.version }}" version 2>/dev/null; then
             echo "Version already published, skipping"

.gitignore

@@ -5,3 +5,5 @@ credentials/
 dist/
 repos/
 .turbo/
+
+.DS_Store

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,17 +96,20 @@ 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)
-- `apps/cli/src/env.ts` — `.env` loading, TOML fallback (npx only) via `apps/cli/src/config/resolver.ts`, credential validation, env flag building
+- `apps/cli/src/env.ts` — `.env` loading, TOML fallback (npx only) via `apps/cli/src/config/resolver.ts`, credential validation, provider-scoped env flag building
+- `apps/cli/src/model-spec.ts` — `SHANNON_AI_MODEL` (`<provider>:<model-id>`) parsing; mirrors `apps/worker/src/ai/models.ts`
 - `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
@@ -127,7 +129,7 @@ Infra (Temporal) runs via `docker-compose.yml`. Workers are ephemeral `docker ru
 - `apps/worker/src/paths.ts` — Centralized path constants (`PROMPTS_DIR`, `CONFIGS_DIR`, `WORKSPACES_DIR`)
 - `apps/worker/src/session-manager.ts` — Agent definitions (`AGENTS` record). Agent types in `apps/worker/src/types/agents.ts`
 - `apps/worker/src/config-parser.ts` — YAML config parsing with JSON Schema validation
-- `apps/worker/src/ai/pi-executor.ts` — pi harness integration (retry disabled; Temporal owns retry)
+- `apps/worker/src/ai/pi/pi-executor.ts` — pi harness integration (agent-level retry disabled so Temporal owns restarts; provider-level retry on, see `apps/worker/src/ai/pi/retry-settings.ts`)
 - `apps/worker/src/services/` — Business logic layer (Temporal-agnostic). Activities delegate here. Key: `agent-execution.ts`, `error-handling.ts`, `container.ts`
 - `apps/worker/src/types/` — Consolidated types: `Result<T,E>`, `ErrorCode`, `AgentName`, `ActivityLogger`, etc.
 - `apps/worker/src/utils/` — Shared utilities (file I/O, formatting, concurrency)
@@ -150,12 +152,13 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig
 5. **Reporting** (`report`) — Executive-level security report
 
 ### 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` filters (`min_severity`, `min_confidence`, `guidance`). `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/settings-writer.ts:writeCodePathPermissionConfig`), and the executor loads the extension when that config is present (`apps/worker/src/ai/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`)
+- **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` for a SARIF 2.1.0 log via `apps/worker/src/services/sarif-renderer.ts`, on by default for exploit runs and opt out with `report.sarif: false`). `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-executor.ts` (`runPiPrompt` → `createAgentSession`, retry disabled so Temporal owns retry). Models resolve through pi-ai in `apps/worker/src/ai/models.ts` (Anthropic / Bedrock / custom base URL via `ModelRegistry`+`AuthStorage`). 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` (read-only child sessions) + `todo_write` are provided as custom tools (`apps/worker/src/ai/tools.ts`); the per-phase MCP collectors are pi custom tools (TypeBox `defineTool` in `apps/worker/src/mcp-server/`). Adaptive thinking (pi's `medium` level) is enabled only on Opus 4.6/4.7/4.8 (`supportsAdaptiveThinking`); every other model runs with thinking `off`. Disable per-scan via `CLAUDE_ADAPTIVE_THINKING=false` (→ `off`) / `core.adaptive_thinking = false` (npx TOML). 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 (`SHANNON_AI_MODEL=openai-codex:<model-id>`) or an `xai` Grok subscription (`SHANNON_AI_MODEL=xai:<model-id>`); the mechanism is provider-agnostic and works for any Pi login. `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
 
@@ -233,7 +236,7 @@ Comments must be **timeless** — no references to this conversation, refactorin
 
 **Entry Points:** `apps/worker/src/temporal/workflows.ts`, `apps/worker/src/temporal/activities.ts`, `apps/worker/src/temporal/worker.ts`
 
-**Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/pi-executor.ts`, `apps/worker/src/ai/settings-writer.ts` (writes `code_path` deny rules to the `@gotgenes/pi-permission-system` global config), `apps/worker/src/config-parser.ts`, `apps/worker/src/services/` (incl. `preflight.ts`, `findings-renderer.ts`, `reporting.ts`), `apps/worker/src/audit/`
+**Core Logic:** `apps/worker/src/session-manager.ts`, `apps/worker/src/ai/pi/pi-executor.ts`, `apps/worker/src/ai/pi/permission-system.ts` (writes `code_path` deny rules to the `@gotgenes/pi-permission-system` global config), `apps/worker/src/config-parser.ts`, `apps/worker/src/services/` (incl. `preflight.ts`, `findings-renderer.ts`, `reporting.ts`), `apps/worker/src/audit/`
 
 **Config:** `docker-compose.yml`, `apps/cli/infra/compose.yml`, `apps/worker/configs/`, `apps/worker/prompts/`, `tsconfig.base.json` (shared compiler options), `turbo.json`, `biome.json`
 
@@ -245,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
@@ -101,16 +119,18 @@ RUN mkdir -p /tmp/.claude/skills && \
 RUN ln -s /app/apps/worker/dist/scripts/save-deliverable.js /usr/local/bin/save-deliverable && \
     chmod +x /app/apps/worker/dist/scripts/save-deliverable.js && \
     ln -s /app/apps/worker/dist/scripts/generate-totp.js /usr/local/bin/generate-totp && \
-    chmod +x /app/apps/worker/dist/scripts/generate-totp.js
+    chmod +x /app/apps/worker/dist/scripts/generate-totp.js && \
+    ln -s /app/apps/worker/dist/scripts/set-report-meta.js /usr/local/bin/set-report-meta && \
+    chmod +x /app/apps/worker/dist/scripts/set-report-meta.js
 
 # 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,25 +1,28 @@
 > [!NOTE]
-> **[Shannon Now Runs on the Pi Harness (Beta) - run it today with `npx @keygraph/shannon@beta`](https://github.com/KeygraphHQ/shannon/discussions/358)**
+> **[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%">
-
-# Shannon - AI Pentester by Keygraph
+<picture>
+<source media="(prefers-color-scheme: dark)" srcset="./assets/github-banner-dark.png">
+<source media="(prefers-color-scheme: light)" srcset="./assets/github-banner-light.png">
+<img src="./assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">
+</picture>
 
 <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. 
+
 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.**
 
 ---
 
-<a href="https://discord.gg/9ZqQPuhJB7"><img src="./assets/discord.png" height="40" alt="Join Discord"></a>
-<a href="https://keygraph.io/"><img src="./assets/Keygraph_Button.png" height="40" alt="Visit Keygraph.io"></a>
+<a href="https://discord.gg/9ZqQPuhJB7"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/discord_button_dark.png"><source media="(prefers-color-scheme: light)" srcset="./assets/discord_button_light.png"><img src="./assets/discord_button_light.png" height="40" alt="Join Discord"></picture></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://keygraph.io/"><picture><source media="(prefers-color-scheme: dark)" srcset="./assets/keygraph_button_dark.png"><source media="(prefers-color-scheme: light)" srcset="./assets/keygraph_button_light.png"><img src="./assets/keygraph_button_light.png" height="40" alt="Visit Keygraph.io"></picture></a>
 
 ---
+
 </div>
 
 > [!TIP]
@@ -35,13 +38,14 @@ 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)
+- [Common Questions](#common-questions)
 
 ## 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.
 
@@ -53,10 +57,16 @@ Thanks to tools like Claude Code and Cursor, your team ships code non-stop. But
 
 Shannon closes that gap by providing on-demand, automated penetration testing that can run against every build or release.
 
+### Why "Shannon"?
+
+It's named after Claude Shannon, the father of information theory. At its core, pentesting is an information problem: every probe reduces uncertainty about a system's state. The best tools maximize the signal gained from every request, turning those bits of knowledge into an exploit path.
+
+Also, we wanted you to be able to say, "Hey Claude, run Shannon" to find all the security flaws in your vibe-coded app.
+
 ## Shannon in Action
 
 <p align="center">
-  <img src="assets/shannon-action.gif" alt="Shannon running an autonomous pentest" width="100%">
+  <img src="assets/Shannon3GIF.gif" alt="Shannon running an autonomous pentest" width="100%">
 </p>
 
 Sample penetration test reports from intentionally vulnerable applications, produced by Shannon Open Source:
@@ -73,7 +83,8 @@ 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 is recommended. AWS Bedrock and compatible proxy setups are documented separately.
+- **AI provider credentials**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, [any other provider](docs/ai-providers.md#any-other-provider) in the harness catalogue, and any endpoint that speaks the Anthropic Messages API or the OpenAI Chat Completions or Responses API through a [custom base URL](docs/ai-providers.md#custom-base-url). You bring your own key, and Keygraph never proxies your model traffic. Shannon is provider-agnostic. See [AI providers](docs/ai-providers.md#suggested-models) for suggested model IDs.
+- **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
 
@@ -92,6 +103,13 @@ 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 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.
+> - **xAI (Grok):** The latest version of Shannon supports xAI subscriptions. Follow the [xAI subscription setup guide](docs/ai-providers.md#xai-grok-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
 
 - **Proof-by-exploitation reports**: Shannon reports validated findings with reproducible proof-of-concept steps instead of speculative warnings.
@@ -100,6 +118,8 @@ For source builds, authenticated scans, provider-specific setup, and platform no
 - **Authenticated testing**: configuration files can describe login flows, test credentials, TOTP, email-based login flows, focus areas, and rules of engagement.
 - **OWASP-focused coverage**: Shannon targets exploitable Injection, XSS, SSRF, Broken Authentication, and Broken Authorization issues.
 - **Resumable workspaces**: Shannon can resume interrupted runs without re-running completed agents.
+- **Machine-readable output**: Shannon emits findings as structured JSON, and as SARIF 2.1.0 by default on exploit-mode scans (opt out with `report.sarif: "false"`). SARIF is the OASIS standard for static analysis results, so findings flow into any code scanning service, vulnerability management platform, security dashboard, or CI/CD pipeline that reads it.
+- **Bring your own key, provider-agnostic**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, and any endpoint speaking the Anthropic Messages API or the OpenAI Chat Completions or Responses API, including self-hosted models served through Ollama, vLLM, or LM Studio and gateways such as OpenRouter and LiteLLM. You supply the credentials, so source code and model traffic stay inside your infrastructure. Local and self-hosted models are technically supported but not recommended: they may not follow Shannon's instructions or tool-use constraints as reliably as frontier models, so take that path only if you know how your chosen model behaves.
 
 ## Editions
 
@@ -185,8 +205,8 @@ Use these guides for operational detail:
 | Guide | Use it for |
 | --- | --- |
 | [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, report filters, and rate-limit settings. |
-| [AI providers](docs/ai-providers.md) | Anthropic, AWS Bedrock, and custom Anthropic-compatible endpoints. |
+| [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 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. |
@@ -203,13 +223,13 @@ Important limitations:
 
 - Shannon Open Source focuses on actively exploitable issues such as Injection, XSS, SSRF, Broken Authentication, and Broken Authorization. Broader static-analysis coverage, including vulnerable dependencies and insecure configurations, is delivered through the Keygraph platform.
 - Findings still require human review. LLM-generated reports can contain weakly supported or incorrect details.
-- Shannon is officially supported with Claude models. Smaller, alternative, or proxied non-Claude models may be incomplete or unstable.
+- Anthropic, OpenAI, xAI, and AWS Bedrock are built-in providers, and any Anthropic Messages API or OpenAI Chat Completions or Responses API endpoint works through a custom base URL. Model capability varies, and a model that does not follow Shannon's instructions or tool-use constraints reliably will produce weaker results.
 - A full run can take roughly 1 to 1.5 hours and may incur LLM API costs depending on model pricing and application complexity.
 - Do not scan untrusted or adversarial codebases. AI-powered tools that read source code can be exposed to prompt injection.
 
 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).
 
@@ -242,6 +262,32 @@ Stay connected:
 - [Twitter/X: @KeygraphHQ](https://twitter.com/KeygraphHQ)
 - [LinkedIn: Keygraph](https://linkedin.com/company/keygraph)
 
+## Common Questions
+
+### Can I self-host Shannon?
+
+Yes. Shannon Open Source runs entirely on your own infrastructure in an ephemeral Docker container. Your source code is mounted read-only and never leaves your environment.
+
+### Does Shannon support bring your own key (BYOK)?
+
+Yes, always. You provide the LLM credentials Shannon uses to run a pentest, in every deployment, open source and commercial. Keygraph never proxies your model traffic.
+
+### Does Shannon output SARIF?
+
+Yes. Shannon emits SARIF 2.1.0, the OASIS standard format for static analysis results, alongside structured JSON. Any SARIF consumer reads it: code scanning services, vulnerability management platforms, security dashboards, and CI/CD pipelines. It is written by default on exploit-mode scans; set `report.sarif` to `"false"` in your configuration file to opt out.
+
+### Which AI providers does Shannon support?
+
+Anthropic, OpenAI, xAI, and AWS Bedrock are built in and configured directly by provider ID. Beyond those, Shannon runs on any endpoint that implements the Anthropic Messages API or the OpenAI Chat Completions or Responses API, reached through a custom base URL. The rule is the API format, not the vendor. Shannon uses a single unified model setting throughout a pentest.
+
+### Can I run Shannon on a local or self-hosted model?
+
+Technically yes, but it is not recommended. Shannon works with local models served through Ollama, vLLM, or LM Studio, which expose an OpenAI-compatible endpoint, as well as routers such as OpenRouter and gateways such as LiteLLM. Point Shannon at the endpoint with a custom base URL. Capability varies, and a model that does not follow Shannon's instructions or tool-use constraints reliably will produce weaker pentests than a frontier model, so take this path only if you know how your chosen model behaves. See [AI providers](docs/ai-providers.md#custom-base-url).
+
+### Does Shannon actually exploit vulnerabilities, or just scan?
+
+Shannon executes real exploits. It reports a finding only when it has produced a working proof-of-concept, and discards hypotheses it cannot prove. It is a pentester, not a scanner.
+
 <p align="center">
   <b>Built by <a href="https://keygraph.io">Keygraph</a></b>
 </p>

apps/cli/README.md

@@ -1,22 +1,60 @@
 <div align="center">
 
-<img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/github-banner.png" alt="Shannon — AI Pentester for Web Applications and APIs" width="100%">
+<img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/github-banner-light.png" alt="Shannon, AI Pentester for Web Apps and APIs, by Keygraph" width="100%">
 
-# Shannon — AI Pentester by Keygraph
+### Shannon is an autonomous, AI pentester for web applications and APIs.
 
-Shannon is an autonomous, white-box AI pentester for web applications and APIs. <br />
-It analyzes your source code, identifies attack vectors, and executes real exploits to prove vulnerabilities before they reach production.
+It analyzes your source code, identifies attack paths, and executes real exploits to prove vulnerabilities before they reach production.
+
+**This package is Shannon Open Source: the full agent, run locally from your command line.**
 
 ---
 
-<a href="https://github.com/KeygraphHQ/shannon/discussions/categories/announcements"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/announcements.png" height="40" alt="Announcements"></a>
-<a href="https://discord.gg/9ZqQPuhJB7"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/discord.png" height="40" alt="Join Discord"></a>
-<a href="https://keygraph.io/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/Keygraph_Button.png" height="40" alt="Visit Keygraph.io"></a>
-<a href="https://www.linkedin.com/company/keygraph/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/linkedin.png" height="40" alt="Follow Us on Linkedin"></a>
+<a href="https://discord.gg/9ZqQPuhJB7"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/discord_button_light.png" height="40" alt="Join Discord"></a>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://keygraph.io/"><img src="https://raw.githubusercontent.com/KeygraphHQ/shannon/main/assets/keygraph_button_light.png" height="40" alt="Visit Keygraph.io"></a>
 
 ---
 
-**Full README and usage guide**  
-[https://github.com/KeygraphHQ/shannon#readme](https://github.com/KeygraphHQ/shannon#readme)
-
 </div>
+
+## Quick Start
+
+### Prerequisites
+
+- **Docker**: required for the worker container.
+- **Node.js 18+**: required for the recommended `npx` workflow.
+- **AI provider credentials**: Shannon runs on Anthropic, OpenAI, xAI, AWS Bedrock, any other provider in the harness catalogue, and any endpoint that speaks the Anthropic Messages API or the OpenAI Chat Completions or Responses API through a custom base URL. You bring your own key, and Keygraph never proxies your model traffic. Shannon is provider-agnostic.
+- **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.
+
+### Run Shannon
+
+> **Warning:** Shannon actively executes exploits. Run it only against applications and environments you own or have explicit written authorization to test. Do not run Shannon against production systems.
+
+```bash
+# Configure credentials with the interactive wizard.
+npx @keygraph/shannon setup
+
+# Run a pentest against a source-available target.
+npx @keygraph/shannon start -u https://your-app.com -r /path/to/your-repo
+```
+
+Shannon pulls the worker image from Docker Hub, starts the required local infrastructure, mounts the target repository read-only inside an ephemeral worker container, and writes results to a local workspace.
+
+## Editions
+
+Shannon ships in two ways. **Shannon Open Source** is this package: the standalone pentester you run yourself, on demand, and complete in that lane. The **Keygraph platform** is the commercial product that runs an enhanced build of Shannon continuously and closes the full AppSec lifecycle around it - code analysis, finding management, automated remediation, verification, and enterprise deployment.
+
+## Documentation
+
+**Full README, guides, and usage documentation:** [github.com/KeygraphHQ/shannon](https://github.com/KeygraphHQ/shannon#readme)
+
+## License
+
+Shannon Open Source is licensed under the [GNU Affero General Public License v3.0](https://github.com/KeygraphHQ/shannon/blob/main/LICENSE).
+
+Commercial and enterprise licensing is available for organizations that need different license terms, commercial support, private redistribution, managed-service use, or broader deployment options, including the Keygraph platform.
+
+For commercial licensing, contact [shannon@keygraph.io](mailto:shannon@keygraph.io).
+
+<p align="center">
+  <b>Built by <a href="https://keygraph.io">Keygraph</a></b>
+</p>

apps/cli/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@keygraph/shannon",
   "version": "0.0.0",
-  "description": "Shannon - Autonomous white-box AI pentester for web applications and APIs by Keygraph",
+  "description": "Shannon is an autonomous white-box AI pentester for web applications and APIs, by Keygraph.",
   "type": "module",
   "main": "dist/index.mjs",
   "bin": {
@@ -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"
@@ -34,8 +35,12 @@
     "appsec",
     "keygraph"
   ],
-  "author": "",
+  "author": "Keygraph, Inc.",
   "license": "AGPL-3.0-only",
+  "bugs": {
+    "url": "https://github.com/KeygraphHQ/shannon/issues"
+  },
+  "homepage": "https://github.com/KeygraphHQ/shannon#readme",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/KeygraphHQ/shannon.git",

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/chrome.ts

@@ -0,0 +1,159 @@
+/**
+ * Section chrome — the sunset-ramp hierarchy beneath the splash wordmark.
+ * (Distinct from ui.ts, which holds the spinner/step helpers.)
+ *
+ * Three treatments, one job each:
+ *   rule()    static blocks that print once — `start`, `status`, a log's header
+ *   gutter()  streaming output, where a section scrolls off the top of the screen
+ *   panel()   the single summary block at the end of a run
+ *
+ * Presentation only. None of this is ever written to workflow.log — the file on disk
+ * stays plain text so `tail`, `grep`, and the completion regex in commands/logs.ts keep
+ * working against it.
+ */
+
+import { supportsColor } from './tty.js';
+
+/**
+ * Sunset ramp, yellow at the top row down to burnt orange at the base.
+ * The wordmark paints row i with stop i and edges it with stop i + 1; section chrome
+ * draws from the same seven stops so the hierarchy reads as one family.
+ * `xterm` is the 256-color approximation for terminals without 24-bit color.
+ */
+export 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 },
+];
+
+/** Half-block bar for streaming sections — the wordmark's █ at one eighth the weight. */
+const BAR = '▌';
+
+/** Columns reserved to the left of every section, matching the existing output grid. */
+const INDENT = 2;
+
+/** Rules stop here even in a wide terminal; a rule spanning 200 columns reads as a divider, not a header. */
+const MAX_RULE = 64;
+
+export interface Palette {
+  color: boolean;
+  RESET: string;
+  WHITE: string;
+  GRAY: string;
+  DIM: string;
+  RED: string;
+  /** The seven sunset stops, ready to emit. Empty strings when color is off. */
+  ramp: string[];
+  /** Ramp stop 0 — the solid yellow used for every static rule. */
+  YELLOW: string;
+}
+
+/**
+ * Build the escape set for the current terminal, degrading 24-bit → 256-color → bare text.
+ * Resolved per call rather than at import so NO_COLOR/FORCE_COLOR are honored whenever they land.
+ */
+export function palette(): Palette {
+  const color = supportsColor();
+  const truecolor = color && /truecolor|24bit/i.test(process.env.COLORTERM ?? '');
+
+  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`;
+  });
+
+  return {
+    color,
+    RESET: color ? '\x1b[0m' : '',
+    WHITE: color ? '\x1b[1;97m' : '',
+    GRAY: color ? '\x1b[0;37m' : '',
+    DIM: color ? '\x1b[90m' : '',
+    RED: color ? '\x1b[0;31m' : '',
+    ramp,
+    YELLOW: ramp[0] ?? '',
+  };
+}
+
+/** Usable width, leaving the indent and a column of breathing room at the right edge. */
+function columns(): number {
+  return process.stdout.columns && process.stdout.columns > 0 ? process.stdout.columns : 80;
+}
+
+/** Printed width of a string, ignoring any escapes already embedded in it. */
+export function visibleWidth(text: string): number {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: matching SGR escapes is the point
+  return text.replace(/\x1b\[[0-9;]*m/g, '').length;
+}
+
+/**
+ * Option A — a static section header: the existing label, then a solid yellow rule.
+ * The label keeps whatever case and punctuation it already had; only the rule is added.
+ * Degrades to an undecorated label when the terminal is too narrow to carry one.
+ */
+export function rule(label: string, indent = INDENT): string {
+  const { WHITE, YELLOW, RESET } = palette();
+  const pad = ' '.repeat(indent);
+  const width = Math.min(MAX_RULE, columns() - indent - 1);
+  const dashes = width - visibleWidth(label) - 1;
+
+  if (dashes < 2) return `${pad}${WHITE}${label}${RESET}`;
+  return `${pad}${WHITE}${label}${RESET} ${YELLOW}${'─'.repeat(dashes)}${RESET}`;
+}
+
+/**
+ * Grey the label half of an aligned `Label:   value` line, leaving the value at default
+ * weight. Purely additive: the string's own characters are never rewritten, so alignment
+ * that was already correct stays correct.
+ */
+export function field(line: string): string {
+  const { GRAY, RESET } = palette();
+  const match = /^(\s*)([A-Za-z][A-Za-z ]*:)(\s*)(.*)$/.exec(line);
+  if (!match) return line;
+  return `${match[1]}${GRAY}${match[2]}${RESET}${match[3]}${match[4]}`;
+}
+
+/**
+ * Option C — one line of a streaming section, carrying the section's bar in the gutter.
+ * `stop` indexes the sunset ramp and wraps, so consecutive sections stay distinguishable
+ * however many a run produces.
+ */
+export function gutter(text: string, stop: number, indent = INDENT): string {
+  const { ramp, RESET } = palette();
+  const color = ramp[((stop % ramp.length) + ramp.length) % ramp.length] ?? '';
+  const pad = ' '.repeat(indent);
+  // Trailing space is dropped on empty lines so sections don't emit trailing whitespace.
+  return text ? `${pad}${color}${BAR}${RESET} ${text}` : `${pad}${color}${BAR}${RESET}`;
+}
+
+/**
+ * Option E — the framed summary block, used once at the end of a run.
+ * Falls back to a rule plus indented lines when the terminal is too narrow to hold the
+ * frame, since a box that wraps is worse than no box at all.
+ */
+export function panel(title: string, body: string[], indent = INDENT): string[] {
+  const { WHITE, YELLOW, RESET } = palette();
+  const pad = ' '.repeat(indent);
+  const titleWidth = visibleWidth(title);
+  const widest = body.reduce((max, line) => Math.max(max, visibleWidth(line)), 0);
+
+  const available = columns() - indent - 6;
+  const inner = Math.max(titleWidth + 1, widest);
+
+  if (available < inner || available < titleWidth + 3) {
+    return [rule(title, indent), '', ...body.map((line) => `${pad}  ${line}`)];
+  }
+
+  const frame = (s: string): string => `${YELLOW}${s}${RESET}`;
+  const top = `${pad}${frame('╭─')} ${WHITE}${title}${RESET} ${frame(`${'─'.repeat(inner + 1 - titleWidth)}╮`)}`;
+  const bottom = `${pad}${frame(`╰${'─'.repeat(inner + 4)}╯`)}`;
+
+  const rows = body.map((line) => {
+    const fill = ' '.repeat(inner - visibleWidth(line));
+    return `${pad}${frame('│')}  ${line}${fill}  ${frame('│')}`;
+  });
+
+  return [top, ...rows, bottom];
+}

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

@@ -1,19 +1,20 @@
 /**
- * `shannon build` command — build the worker Docker image locally.
- * Only available in local mode (running from cloned repository).
+ * `shannon build` command — build the worker Docker image from the repository.
+ * Requires a clone (Dockerfile in the working directory).
  */
 
-import { buildImage } from '../docker.js';
-import { isLocal } from '../mode.js';
+import { buildImage, canBuildImage, ensureDocker } from '../docker.js';
+import { fail } from '../errors.js';
 
-export function build(noCache: boolean): void {
-  if (!isLocal()) {
-    console.error('ERROR: Build is only available when running from the Shannon repository');
-    console.error('  (Dockerfile not found in current directory)');
-    console.error('');
-    console.error('For npx usage, run: shannon update');
-    process.exit(1);
+export function build(noCache: boolean, version: string): void {
+  ensureDocker();
+
+  if (!canBuildImage()) {
+    fail(
+      'Build is only available when running from the Shannon repository',
+      '  (Dockerfile not found in current directory)',
+    );
   }
 
-  buildImage(noCache);
+  buildImage(noCache, version);
 }

apps/cli/src/commands/logs.ts

@@ -1,18 +1,24 @@
 /**
  * `shannon logs` command — tail a scan's live log.
  *
- * Uses chokidar for reliable cross-platform file watching and
- * bounded synchronous reads to prevent duplicate output.
+ * The log file is streamed for its content; completion is decided by Temporal (the
+ * workflow's status), so a worker that dies mid-run can't leave the tail hanging. Uses
+ * chokidar for reliable cross-platform file watching and bounded synchronous reads to
+ * prevent duplicate output.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import { setTimeout as sleep } from 'node:timers/promises';
 import { watch } from 'chokidar';
+import { field } from '../chrome.js';
+import { fail } from '../errors.js';
 import { getWorkspacesDir } from '../home.js';
+import { LogRenderer } from '../log-render.js';
 import { resolveRunFile } from '../paths.js';
-
-// Match the exact line the worker writes — anchored to prevent false positives from agent output
-const COMPLETION_PATTERN = /^Scan (COMPLETED|FAILED)$/m;
+import { resolveWorkflowId } from '../session.js';
+import { waitForWorkflowClose } from '../temporal-client.js';
+import { stdoutIsTerminal } from '../tty.js';
 
 /** Read a byte range from a file and return it as a UTF-8 string. */
 function readRange(filePath: string, start: number, end: number): string {
@@ -28,7 +34,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 +55,129 @@ 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',
+  );
+}
+
+export interface TailOptions {
+  /** Workflow whose Temporal status decides when the tail stops. Without it, only Ctrl-C ends the tail. */
+  readonly workflowId?: string;
+  /** Called if the tail ends because Temporal became unreachable, with the captured error. */
+  readonly onUnreachable?: (lastError: string) => void;
+}
+
+/** Outcome of a tail: whether the streamed log already contained the worker's `Scan FAILED` block. */
+export interface TailResult {
+  readonly sawFailure: boolean;
+}
+
+// The worker writes this exact line at the head of its terminal failure summary.
+const FAILURE_MARKER = /^Scan FAILED$/m;
+
+/**
+ * Stream a scan's log to the terminal until the workflow closes (completion comes from Temporal,
+ * or Ctrl-C). A Temporal outage is warned about and, if sustained, ends the tail with a diagnostic.
+ * Never exits the process: plain `logs` exits; `start --follow` reads the workflow outcome first.
+ * Reports whether the log already showed the failure, so a caller need not print it a second time.
+ */
+export function tailUntilComplete(logFile: string, opts: TailOptions = {}): Promise<TailResult> {
+  return new Promise((resolve) => {
+    let position = 0;
+    let done = false;
+    let sawFailure = false;
+    // Decorates the streamed log for the terminal; a pass-through when colour is off, so
+    // piped/redirected output stays byte-identical and the failure check still sees raw text.
+    const renderer = new LogRenderer();
+    const controller = new AbortController();
+    let watcher: ReturnType<typeof watch> | undefined;
+
+    /** Output any new content appended since the last read. */
+    function flush(): void {
+      try {
+        const { size } = fs.statSync(logFile);
+        if (size <= position) return;
+        const data = readRange(logFile, position, size);
+        process.stdout.write(renderer.write(data));
+        position = size;
+        if (!sawFailure && FAILURE_MARKER.test(data)) {
+          sawFailure = true;
+        }
+      } catch {
+        // File not present yet or transiently unreadable — nothing to flush this round.
+      }
+    }
+
+    function finish(): void {
+      if (done) return;
+      done = true;
+      process.stdout.write(renderer.end());
+      controller.abort();
+      if (watcher) {
+        watcher.close().finally(() => resolve({ sawFailure }));
+        // Safety net — resolve anyway if watcher.close() stalls.
+        setTimeout(() => resolve({ sawFailure }), 1000).unref();
+      } else {
+        resolve({ sawFailure });
+      }
+    }
+
+    // 1. Output existing content, then stream anything appended.
+    flush();
+    watcher = watch(logFile, { persistent: true });
+    watcher.on('change', () => flush());
+
+    // 2. Ctrl-C stops watching.
+    process.on('SIGINT', finish);
+
+    // 3. Temporal decides completion. Without a workflow id, the tail relies on Ctrl-C alone.
+    if (opts.workflowId) {
+      waitForWorkflowClose(opts.workflowId, {
+        signal: controller.signal,
+        onConnectionTrouble: (lastError) => {
+          if (!done) console.error(`\n⚠ Lost contact with Temporal, retrying… (${lastError})`);
+        },
+        onReconnected: () => {
+          if (!done) console.error('  Reconnected to Temporal.');
+        },
+      })
+        .then(async (end) => {
+          if (done) return;
+          // Flush, let a just-written final summary land, then flush the tail once more.
+          flush();
+          await sleep(750).catch(() => {});
+          flush();
+          if (end.reason === 'unreachable') {
+            console.error('\nScan watch aborted: lost contact with Temporal.');
+            console.error(`  Last error: ${end.lastError}`);
+            console.error('  Temporal may have crashed — check `docker compose logs temporal`.');
+            opts.onUnreachable?.(end.lastError);
+          }
+          finish();
+        })
+        .catch(() => {
+          // waitForWorkflowClose never rejects; guard only against an aborted race.
+        });
+    }
+  });
 }
 
 export function logs(workspaceId: string): void {
   const logFile = resolveLogFile(workspaceId);
-  let position = 0;
+  const workflowId = resolveWorkflowId(workspaceId);
+  console.error(stdoutIsTerminal() ? field(`Tailing scan log: ${logFile}`) : 'Tailing scan log');
 
-  /**
-   * 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);
+  let unreachable = false;
+  tailUntilComplete(logFile, {
+    ...(workflowId ? { workflowId } : {}),
+    onUnreachable: () => {
+      unreachable = true;
+    },
+  }).finally(() => process.exit(unreachable ? 1 : 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

@@ -1,59 +1,167 @@
 /**
  * `npx @keygraph/shannon setup` — interactive TUI wizard for one-time credential configuration.
  *
- * Walks the user through selecting a provider and entering credentials,
- * then persists everything to ~/.shannon/config.toml with 0o600 permissions.
+ * Walks the user through selecting a provider, entering credentials, and naming
+ * the model that runs the whole scan, then persists everything to
+ * ~/.shannon/config.toml with 0o600 permissions.
  */
 
 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 { 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');
 
-type Provider = 'anthropic' | 'custom_base_url' | 'bedrock';
+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
+ * that supplies the credential, and for OpenAI it also picks which of the two
+ * OpenAI APIs Shannon calls.
+ */
+const GATEWAY_DIALECTS: readonly {
+  value: string;
+  label: string;
+  provider: 'anthropic' | 'openai';
+  format?: OpenAiFormat;
+}[] = [
+  { value: 'anthropic', label: 'Anthropic Messages', provider: 'anthropic' },
+  {
+    value: 'openai-chat-completions',
+    label: 'OpenAI Chat Completions',
+    provider: 'openai',
+    format: 'chat-completions',
+  },
+  { value: 'openai-responses', label: 'OpenAI Responses', provider: 'openai', format: 'responses' },
+];
+
+/** 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, 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
-  const provider = await p.select({
+  // 1. Select provider. "Custom Base URL" is a route, not a provider — it asks
+  //    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: [
-      { value: 'anthropic' as const, label: 'Claude Direct', hint: 'recommended' },
-      { value: 'custom_base_url' as const, label: 'Custom Base URL', hint: 'proxies, gateways' },
-      { value: 'bedrock' as const, label: 'Claude via AWS Bedrock' },
+      { value: 'anthropic' as const, label: 'Anthropic', hint: 'Claude models - recommended' },
+      { value: 'openai' as const, label: 'OpenAI', hint: 'GPT models' },
+      { 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(provider)) return cancelAndExit();
+  if (p.isCancel(selected)) return cancelAndExit();
 
-  const config = await setupProvider(provider as Provider);
+  // 2. Credentials — and, on the gateway route, the endpoint and its dialect.
+  const { provider, config, gateway } = await setupSelection(selected);
 
-  // 2. Adaptive thinking
-  await maybePromptAdaptiveThinking(config);
+  // 3. The model that runs every phase.
+  const modelId = await promptModel(provider);
+  config.core = { ...config.core, model: `${provider}:${modelId}` };
+  if (gateway) config.core = { ...config.core, base_url: gateway.baseUrl };
 
-  // 3. Save config
   saveConfig(config);
 
   const configPath = path.join(SHANNON_HOME, 'config.toml');
+  const summary = [`Provider   ${provider}`, `Model      ${modelId}`];
+  if (gateway) summary.push(`Endpoint   ${gateway.baseUrl}`);
+  if (gateway?.format) summary.push(`API        ${gateway.format}`);
+
   p.log.success(`Configuration saved to ${configPath}`);
+  p.log.info(summary.join('\n'));
   p.outro('Run `npx @keygraph/shannon start` to begin a scan.');
 }
 
-async function setupProvider(provider: Provider): 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();
     case 'anthropic':
       return setupAnthropic();
-    case 'custom_base_url':
-      return setupCustomBaseUrl();
-    case 'bedrock':
-      return setupBedrock();
+    case 'openai':
+      return { openai: { api_key: await promptSecret('Enter your OpenAI API key') } };
+    case 'xai':
+      return { xai: { api_key: await promptSecret('Enter your xAI API key') } };
   }
 }
 
+/**
+ * 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> {
@@ -66,112 +174,13 @@ async function setupAnthropic(): Promise<ShannonConfig> {
   });
   if (p.isCancel(authMethod)) return cancelAndExit();
 
-  const config: ShannonConfig = {};
-
   if (authMethod === 'oauth') {
     const token = await promptSecret('Enter your OAuth token');
-    config.anthropic = { oauth_token: token };
-  } else {
-    const apiKey = await promptSecret('Enter your Anthropic API key');
-    config.anthropic = { api_key: apiKey };
+    return { anthropic: { oauth_token: token } };
   }
 
-  const customizeModels = await p.confirm({
-    message:
-      'Do you want to change the default models?\n' +
-      '    Small  - claude-haiku-4-5-20251001\n' +
-      '    Medium - claude-sonnet-4-6\n' +
-      '    Large  - claude-opus-4-8',
-    initialValue: false,
-  });
-  if (p.isCancel(customizeModels)) return cancelAndExit();
-
-  if (customizeModels) {
-    const small = await p.text({
-      message: 'Small model ID',
-      initialValue: 'claude-haiku-4-5-20251001',
-      validate: required('Small model ID is required'),
-    });
-    if (p.isCancel(small)) return cancelAndExit();
-
-    const medium = await p.text({
-      message: 'Medium model ID',
-      initialValue: 'claude-sonnet-4-6',
-      validate: required('Medium model ID is required'),
-    });
-    if (p.isCancel(medium)) return cancelAndExit();
-
-    const large = await p.text({
-      message: 'Large model ID',
-      initialValue: 'claude-opus-4-8',
-      validate: required('Large model ID is required'),
-    });
-    if (p.isCancel(large)) return cancelAndExit();
-
-    config.models = { small, medium, large };
-  }
-
-  return config;
-}
-
-async function setupCustomBaseUrl(): Promise<ShannonConfig> {
-  const baseUrl = await p.text({
-    message: 'Endpoint URL',
-    placeholder: 'https://your-proxy.example.com',
-    validate: (value) => {
-      if (!value) return 'Endpoint URL is required';
-      try {
-        new URL(value);
-      } catch {
-        return 'Must be a valid URL';
-      }
-      return undefined;
-    },
-  });
-  if (p.isCancel(baseUrl)) return cancelAndExit();
-
-  const authToken = await promptSecret('Enter the auth token for the custom endpoint');
-
-  const config: ShannonConfig = {
-    custom_base_url: { base_url: baseUrl, auth_token: authToken },
-  };
-
-  const customizeModels = await p.confirm({
-    message:
-      'Do you want to change the default models?\n' +
-      '    Small  - claude-haiku-4-5-20251001\n' +
-      '    Medium - claude-sonnet-4-6\n' +
-      '    Large  - claude-opus-4-8',
-    initialValue: false,
-  });
-  if (p.isCancel(customizeModels)) return cancelAndExit();
-
-  if (customizeModels) {
-    const small = await p.text({
-      message: 'Small model ID',
-      initialValue: 'claude-haiku-4-5-20251001',
-      validate: required('Small model ID is required'),
-    });
-    if (p.isCancel(small)) return cancelAndExit();
-
-    const medium = await p.text({
-      message: 'Medium model ID',
-      initialValue: 'claude-sonnet-4-6',
-      validate: required('Medium model ID is required'),
-    });
-    if (p.isCancel(medium)) return cancelAndExit();
-
-    const large = await p.text({
-      message: 'Large model ID',
-      initialValue: 'claude-opus-4-8',
-      validate: required('Large model ID is required'),
-    });
-    if (p.isCancel(large)) return cancelAndExit();
-
-    config.models = { small, medium, large };
-  }
-
-  return config;
+  const apiKey = await promptSecret('Enter your Anthropic API key');
+  return { anthropic: { api_key: apiKey } };
 }
 
 async function setupBedrock(): Promise<ShannonConfig> {
@@ -184,49 +193,121 @@ async function setupBedrock(): Promise<ShannonConfig> {
 
   const token = await promptSecret('Enter your AWS Bearer Token');
 
-  const small = await p.text({
-    message: 'Small model ID',
-    placeholder: 'us.anthropic.claude-haiku-4-5-20251001-v1:0',
-    validate: required('Small model ID is required'),
-  });
-  if (p.isCancel(small)) return cancelAndExit();
+  return { bedrock: { region, token } };
+}
 
-  const medium = await p.text({
-    message: 'Medium model ID',
-    placeholder: 'us.anthropic.claude-sonnet-4-6',
-    validate: required('Medium model ID is required'),
-  });
-  if (p.isCancel(medium)) return cancelAndExit();
+interface GatewaySetup {
+  provider: CuratedProviderId;
+  config: ShannonConfig;
+  baseUrl: string;
+  format?: OpenAiFormat;
+}
 
-  const large = await p.text({
-    message: 'Large model ID',
-    placeholder: 'us.anthropic.claude-opus-4-8',
-    validate: required('Large model ID is required'),
+/**
+ * Gateway route: the endpoint decides where requests go, but the format still
+ * picks a real provider, because that is what supplies the credential and the
+ * wire protocol.
+ */
+async function setupGateway(): Promise<GatewaySetup> {
+  const choice = await p.select({
+    message: 'API format',
+    options: GATEWAY_DIALECTS.map(({ value, label }) => ({ value, label })),
   });
-  if (p.isCancel(large)) return cancelAndExit();
+  if (p.isCancel(choice)) return cancelAndExit();
 
-  return {
-    bedrock: { use: true, region, token },
-    models: { small, medium, large },
-  };
+  const dialect = GATEWAY_DIALECTS.find((entry) => entry.value === choice);
+  if (!dialect) return cancelAndExit();
+  const provider = dialect.provider;
+
+  const baseUrl = await p.text({
+    message: 'Endpoint URL',
+    placeholder: 'https://llm-gateway.example.com',
+    validate: (value) => {
+      if (!value) return 'Endpoint URL is required';
+      try {
+        new URL(value);
+      } catch {
+        return 'Must be a valid URL';
+      }
+      return undefined;
+    },
+  });
+  if (p.isCancel(baseUrl)) return cancelAndExit();
+
+  const authToken = await promptSecret('Enter the auth token for the endpoint');
+  const config: ShannonConfig =
+    provider === 'anthropic'
+      ? { anthropic: { api_key: authToken } }
+      : { openai: { api_key: authToken, ...(dialect.format && { format: dialect.format }) } };
+
+  return { provider, config, baseUrl, ...(dialect.format && { format: dialect.format }) };
+}
+
+// === Model Selection ===
+
+/**
+ * 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: string): Promise<string> {
+  const suggestions = isCuratedProvider(provider) ? MODEL_SUGGESTIONS[provider] : [];
+
+  if (suggestions.length === 0) {
+    return promptModelId(provider, modelIdPlaceholder(provider));
+  }
+
+  const choice = await p.select({
+    message: 'Model',
+    options: [
+      ...suggestions.map((model) => ({ value: model, label: model })),
+      { value: CUSTOM_MODEL, label: 'Enter a model ID…' },
+    ],
+  });
+  if (p.isCancel(choice)) return cancelAndExit();
+
+  if (choice === CUSTOM_MODEL) {
+    return promptModelId(provider, modelIdPlaceholder(provider));
+  }
+  return choice as string;
+}
+
+/**
+ * A leading `<provider>:` naming a supported provider other than the selected
+ * one. Bedrock model IDs carry their own colons (`…-v1:0`), so only a genuine
+ * provider id counts as a prefix.
+ */
+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 (CURATED_PROVIDERS as readonly string[]).includes(head) ? head : undefined;
+}
+
+/**
+ * Ask for a model ID. The provider is already chosen, so this takes the bare ID
+ * and the caller pairs it with the provider — pasting a full `<provider>:<model>`
+ * spec just has its redundant prefix dropped.
+ */
+async function promptModelId(provider: string, placeholder?: string): Promise<string> {
+  const modelId = await p.text({
+    message: 'Model ID',
+    ...(placeholder && { placeholder }),
+    validate: (value) => {
+      if (!value) return 'Model ID is required';
+      const conflicting = conflictingProviderPrefix(provider, value);
+      if (conflicting) return `That model ID is for ${conflicting}, but you selected ${provider}.`;
+      return undefined;
+    },
+  });
+  if (p.isCancel(modelId)) return cancelAndExit();
+
+  return modelId.startsWith(`${provider}:`) ? modelId.slice(provider.length + 1) : modelId;
 }
 
 // === Helpers ===
 
-async function maybePromptAdaptiveThinking(config: ShannonConfig): Promise<void> {
-  const m = config.models;
-  const hasAdaptiveModel = !m || [m.small, m.medium, m.large].some((v) => v && /opus-4-[678]/.test(v));
-  if (!hasAdaptiveModel) return;
-
-  const enable = await p.confirm({
-    message: 'Enable adaptive thinking on Opus 4.6/4.7/4.8? Claude decides when and how deeply to reason.',
-    initialValue: true,
-  });
-  if (p.isCancel(enable)) return cancelAndExit();
-
-  config.core = { ...config.core, adaptive_thinking: enable };
-}
-
 async function promptSecret(message: string): Promise<string> {
   const value = await p.password({
     message,

apps/cli/src/commands/start.ts

@@ -8,13 +8,29 @@
 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 { field, rule } from '../chrome.js';
+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 { FINAL_REPORT_FILENAME, INTERNAL_DIR, resolveConfig, resolveRepo, resolveRunFile } from '../paths.js';
-import { displaySplash } from '../splash.js';
+import { commandPrefix, isLocal } from '../mode.js';
+import { resolveModelSpec } from '../model-spec.js';
+import {
+  expandHome,
+  FINAL_REPORT_PDF_FILENAME,
+  INTERNAL_DIR,
+  resolveConfig,
+  resolveRepo,
+  resolveRunFile,
+} from '../paths.js';
+import { indentFailureSegments } from '../scan/failure.js';
+import { resolveWorkflowId } from '../session.js';
+import { displayPlainBanner, 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;
@@ -23,7 +39,8 @@ export interface StartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  debug: boolean;
+  keepContainer: boolean;
+  follow: boolean;
   version: string;
 }
 
@@ -58,22 +75,34 @@ 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 — identify the run before the Docker/Temporal setup work.
+  const bannerVersion = isLocal() ? undefined : args.version;
+  if (stdoutIsTerminal()) {
+    displaySplash(bannerVersion);
+  } else {
+    displayPlainBanner(bannerVersion);
+  }
+
   // 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();
@@ -108,7 +137,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 });
   }
@@ -116,10 +145,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,
@@ -133,19 +159,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);
   }
 
@@ -162,64 +187,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);
@@ -229,63 +213,139 @@ 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 while Temporal drives
+ * 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. On failure the
+ * root-cause message is printed so a red CI build says why.
+ */
+async function followScan(workspace: string, workspacesDir: string): Promise<never> {
+  const logFile = resolveRunFile(path.join(workspacesDir, workspace), 'workflow.log');
+  const workflowId = resolveWorkflowId(workspace);
+
+  // 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');
+  }
+
+  let temporalUnreachable = false;
+  const { sawFailure } = await tailUntilComplete(logFile, {
+    ...(workflowId && { workflowId }),
+    onUnreachable: () => {
+      temporalUnreachable = true;
+    },
+  });
+
+  // The tail already printed the diagnostic; reading the outcome would only fail the same way.
+  if (temporalUnreachable) {
+    process.exit(1);
+  }
+
+  if (!workflowId) {
+    fail('Scan finished but its workflow id could not be resolved from session.json.');
+  }
+
+  try {
+    const outcome = await getTerminalOutcome(workflowId);
+    if (outcome.kind === 'failed') {
+      // Print the reason only when the streamed log didn't already show the worker's failure
+      // summary — otherwise the worker crashed before writing it, and this is the only report.
+      if (!sawFailure) {
+        console.error(`\nScan failed:\n${indentFailureSegments(outcome.message)}`);
+      }
+      process.exit(1);
+    }
+    process.exit(0);
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    fail('Could not read the scan outcome from Temporal at 127.0.0.1:7233.', `  ${detail}`);
+  }
+}
+
+function printPreservedContainerHint(containerName: string): void {
   console.log('');
-  console.log(`  Worker container preserved: ${containerName}`);
-  console.log(`    Inspect logs: docker logs ${containerName}`);
-  console.log(`    Remove:       docker rm ${containerName}`);
+  console.log(field(`  Worker container preserved: ${containerName}`));
+  console.log(field(`    Inspect logs: docker logs ${containerName}`));
+  console.log(field(`    Remove:       docker rm ${containerName}`));
   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();
 
-  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(`  Workspace:  ${workspace}`);
+  if (interactive && !args.follow) {
+    console.log('  It runs in the background — you can close this terminal.');
+    console.log('');
+  }
+
+  console.log(field(`  Target:     ${args.url}`));
+  console.log(field(`  Repository: ${interactive ? repoPath : path.basename(repoPath)}`));
+  console.log(field(`  Workspace:  ${workspace}`));
   if (args.config) {
-    console.log(`  Config:     ${path.resolve(args.config)}`);
+    console.log(field(`  Config:     ${interactive ? path.resolve(args.config) : path.basename(args.config)}`));
   }
   if (args.pipelineTesting) {
-    console.log('  Mode:       Pipeline Testing');
+    console.log(field('  Mode:       Pipeline Testing'));
   }
 
-  // Surface Fable usage: its safety classifiers route cybersecurity tasks to
-  // Opus 4.8, so those phases run on Opus 4.8 regardless of the tier setting.
-  const fableTiers = (
-    [
-      ['small', process.env.ANTHROPIC_SMALL_MODEL],
-      ['medium', process.env.ANTHROPIC_MEDIUM_MODEL],
-      ['large', process.env.ANTHROPIC_LARGE_MODEL],
-    ] as const
-  ).filter(([, model]) => model && /fable/i.test(model));
-  if (fableTiers.length > 0) {
-    const tierList = fableTiers.map(([tier, model]) => `${tier} (${model})`).join(', ');
-    console.log(`  Note:       ${tierList} set to a Fable model. Fable's safety classifiers`);
-    console.log('              route cybersecurity tasks to Opus 4.8, so those phases run on Opus 4.8.');
+  const spec = resolveModelSpec();
+  if (typeof spec !== 'string') {
+    console.log(field(`  Model:      ${spec.providerId}:${spec.modelId}`));
+  }
+
+  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(rule('Watch scan progress:'));
+    console.log(field(`    Live logs:  ${prefix} logs ${workspace}`));
+    console.log(field(`    Progress:   ${prefix} status ${workspace}`));
   }
 
   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');
-  }
-  console.log('');
-  console.log('  Report (when the scan finishes):');
+  console.log(rule('Report (when the scan finishes):'));
   console.log(`    ${reportPath}`);
   console.log('');
 }

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,8 +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 {
+  type CuratedProviderId,
+  DEFAULT_MODEL_SPEC,
+  GENERIC_API_KEY_ENV,
+  isCuratedProvider,
+  parseModelSpec,
+} from '../model-spec.js';
 
 // === TOML ↔ Env Mapping ===
 
@@ -23,28 +31,40 @@ interface ConfigMapping {
 
 /** Maps every supported env var to its TOML path (section.key) and expected type. */
 const CONFIG_MAP: readonly ConfigMapping[] = [
-  // Core
-  { env: 'CLAUDE_ADAPTIVE_THINKING', toml: 'core.adaptive_thinking', type: 'boolean', boolFormat: 'literal' },
+  // Core — base_url points any provider at a proxy or gateway
+  { env: 'SHANNON_AI_MODEL', toml: 'core.model', type: 'string' },
+  { env: 'SHANNON_AI_BASE_URL', toml: 'core.base_url', type: 'string' },
 
   // Anthropic
   { env: 'ANTHROPIC_API_KEY', toml: 'anthropic.api_key', type: 'string' },
   { env: 'CLAUDE_CODE_OAUTH_TOKEN', toml: 'anthropic.oauth_token', type: 'string' },
 
+  // OpenAI — format picks the wire API a gateway serves
+  { env: 'OPENAI_API_KEY', toml: 'openai.api_key', type: 'string' },
+  { env: 'SHANNON_AI_OPENAI_FORMAT', toml: 'openai.format', type: 'string' },
+
+  // xAI
+  { env: 'XAI_API_KEY', toml: 'xai.api_key', type: 'string' },
+
   // Bedrock
-  { env: 'CLAUDE_CODE_USE_BEDROCK', toml: 'bedrock.use', type: 'boolean' },
   { env: 'AWS_REGION', toml: 'bedrock.region', type: 'string' },
   { env: 'AWS_BEARER_TOKEN_BEDROCK', toml: 'bedrock.token', type: 'string' },
 
-  // Custom Base URL
-  { env: 'ANTHROPIC_BASE_URL', toml: 'custom_base_url.base_url', type: 'string' },
-  { env: 'ANTHROPIC_AUTH_TOKEN', toml: 'custom_base_url.auth_token', type: 'string' },
-
-  // Model tiers
-  { env: 'ANTHROPIC_SMALL_MODEL', toml: 'models.small', type: 'string' },
-  { env: 'ANTHROPIC_MEDIUM_MODEL', toml: 'models.medium', type: 'string' },
-  { env: 'ANTHROPIC_LARGE_MODEL', toml: 'models.large', 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 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;
@@ -81,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);
     }
   }
 
@@ -93,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.`);
   }
 }
 
@@ -118,52 +135,42 @@ function buildSchema(): Map<string, Map<string, TOMLType>> {
   return schema;
 }
 
-/** Check that a provider section has all required fields and dependencies. */
-function validateProviderFields(config: TOMLConfig, provider: string, errors: string[]): void {
-  const section = config[provider] as Record<string, unknown> | undefined;
-  if (!section) return;
-  const keys = Object.keys(section);
-
-  switch (provider) {
-    case 'anthropic':
-      if (!keys.includes('api_key') && !keys.includes('oauth_token')) {
-        errors.push('[anthropic] requires either api_key or oauth_token');
-      }
-      break;
-
-    case 'custom_base_url': {
-      const required = ['base_url', 'auth_token'];
-      const missing = required.filter((k) => !keys.includes(k));
-      if (missing.length > 0) {
-        errors.push(`[custom_base_url] missing required keys: ${missing.join(', ')}`);
-      }
-      break;
+/**
+ * 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. An uncurated
+ * provider draws its credential from the generic [provider] section.
+ */
+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}"`);
     }
-
-    case 'bedrock': {
-      const required = ['use', 'region', 'token'];
-      const missing = required.filter((k) => !keys.includes(k));
-      if (missing.length > 0) {
-        errors.push(`[bedrock] missing required keys: ${missing.join(', ')}`);
-      }
-      validateModelTiers(config, 'bedrock', errors);
-      break;
-    }
-  }
-}
-
-/** Bedrock requires a [models] section with all three tiers. */
-function validateModelTiers(config: TOMLConfig, provider: string, errors: string[]): void {
-  const models = config.models as Record<string, unknown> | undefined;
-  if (!models || typeof models !== 'object') {
-    errors.push(`[${provider}] requires a [models] section with small, medium, and large`);
     return;
   }
 
-  const required = ['small', 'medium', 'large'];
-  const missing = required.filter((k) => !Object.keys(models).includes(k));
-  if (missing.length > 0) {
-    errors.push(`[models] missing required keys for ${provider}: ${missing.join(', ')}`);
+  const sectionName = PROVIDER_SECTIONS[providerId];
+  const section = config[sectionName] as Record<string, unknown> | undefined;
+  const keys = section ? Object.keys(section) : [];
+
+  if (providerId === 'amazon-bedrock') {
+    const missing = ['region', 'token'].filter((k) => !keys.includes(k));
+    if (missing.length > 0) {
+      errors.push(`[bedrock] missing required keys: ${missing.join(', ')}`);
+    }
+    return;
+  }
+
+  if (providerId === 'anthropic') {
+    if (!keys.includes('api_key') && !keys.includes('oauth_token')) {
+      errors.push('[anthropic] requires either api_key or oauth_token');
+    }
+    return;
+  }
+
+  if (!keys.includes('api_key')) {
+    errors.push(`[${sectionName}] requires api_key`);
   }
 }
 
@@ -211,23 +218,19 @@ function validateConfig(config: TOMLConfig): string[] {
     }
   }
 
-  // 4. Only one provider section allowed (ignore empty sections)
-  const PROVIDER_SECTIONS = ['anthropic', 'custom_base_url', 'bedrock'] as const;
-  const present = PROVIDER_SECTIONS.filter((s) => {
-    const section = config[s];
-    return section && typeof section === 'object' && Object.keys(section).length > 0;
-  });
-  if (present.length > 1) {
-    errors.push(
-      `Multiple providers configured: [${present.join('], [')}]. Only one provider section is allowed at a time`,
-    );
+  // 4. core.model must parse and name a supported provider
+  const modelValue = config.core?.model;
+  if (modelValue !== undefined && typeof modelValue !== 'string') {
+    return errors;
+  }
+  const spec = parseModelSpec(modelValue || DEFAULT_MODEL_SPEC);
+  if (typeof spec === 'string') {
+    errors.push(`[core].model — ${spec}`);
+    return errors;
   }
 
-  // 5. Required fields per provider
-  const singleProvider = present.length === 1 ? present[0] : undefined;
-  if (singleProvider) {
-    validateProviderFields(config, singleProvider, errors);
-  }
+  // 5. The selected provider's section must carry a credential
+  validateProviderFields(config, spec.providerId, errors);
 
   return errors;
 }
@@ -251,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

@@ -8,11 +8,13 @@ import { getConfigFile } from '../home.js';
 // === Types ===
 
 export interface ShannonConfig {
-  core?: { adaptive_thinking?: boolean };
+  core?: { model?: string; base_url?: string };
   anthropic?: { api_key?: string; oauth_token?: string };
-  custom_base_url?: { base_url?: string; auth_token?: string };
-  bedrock?: { use?: boolean; region?: string; token?: string };
-  models?: { small?: string; medium?: string; large?: string };
+  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,18 +12,36 @@ import os from 'node:os';
 import path from 'node:path';
 import { setTimeout as sleep } from 'node:timers/promises';
 import { fileURLToPath } from 'node:url';
-import { getMode } from './mode.js';
+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}`;
 }
 
+/** True when the working directory supplies a Dockerfile and build context. */
+export function canBuildImage(): boolean {
+  if (getMode() === 'local') return true;
+  if (!isDevMode()) return false;
+
+  const hasDockerfile = fs.existsSync(path.resolve('Dockerfile'));
+  const hasCompose = fs.existsSync(path.resolve('docker-compose.yml'));
+
+  return hasDockerfile && hasCompose;
+}
+
 function getComposeFile(): string {
   return getMode() === 'local'
     ? path.resolve('docker-compose.yml')
@@ -54,80 +72,116 @@ 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);
 }
 
 /**
- * Build the worker image locally (local mode only).
+ * Build the worker image from the repository, tagged with the name this mode
+ * resolves at run time.
  */
-export function buildImage(noCache: boolean): void {
-  console.log(`Building ${DEV_IMAGE}...`);
+export function buildImage(noCache: boolean, version: string): void {
+  const image = getWorkerImage(version);
+  console.log(`Building ${image}...`);
   const args = ['build'];
   if (noCache) args.push('--no-cache');
-  args.push('-t', DEV_IMAGE, '.');
+  args.push('-t', image, '.');
   execFileSync('docker', args, { stdio: 'inherit' });
-  console.log(`Build complete: ${DEV_IMAGE}`);
+  console.log(`Build complete: ${image}`);
 }
 
 /**
  * Ensure the worker image is available.
- * Local mode: auto-builds if missing. NPX mode: pulls from Docker Hub.
+ * Buildable checkout: auto-builds if missing. Otherwise: pulls from Docker Hub.
  */
 export function ensureImage(version: string): void {
   const image = getWorkerImage(version);
   const exists = runQuiet('docker', ['image', 'inspect', image]);
   if (exists) return;
 
-  if (getMode() === 'local') {
+  if (canBuildImage()) {
     console.log('Shannon image not found, building...');
-    buildImage(false);
+    buildImage(false, version);
   } else {
     console.log(`Pulling ${image}...`);
     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);
   }
@@ -190,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;
@@ -241,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());
 
@@ -292,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);
 
@@ -324,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.`);
+  }
 }
 
 /**
@@ -359,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,25 +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,
+  resolveModelSpec,
+} from './model-spec.js';
 
-/** Environment variables forwarded to worker containers. */
-const FORWARD_VARS = [
-  'ANTHROPIC_API_KEY',
-  'ANTHROPIC_BASE_URL',
-  'ANTHROPIC_AUTH_TOKEN',
-  'CLAUDE_CODE_OAUTH_TOKEN',
-  'CLAUDE_CODE_USE_BEDROCK',
-  'AWS_REGION',
-  'AWS_BEARER_TOKEN_BEDROCK',
-  'ANTHROPIC_SMALL_MODEL',
-  'ANTHROPIC_MEDIUM_MODEL',
-  'ANTHROPIC_LARGE_MODEL',
-  'CLAUDE_ADAPTIVE_THINKING',
+/**
+ * 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',
+  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. An
+ * uncurated provider has none — it relies on the common SHANNON_AI_API_KEY.
+ */
+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.
@@ -39,15 +87,19 @@ export function loadEnv(): void {
 }
 
 /**
- * Build `-e KEY=VALUE` flags for docker run, only for set variables.
+ * 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'];
 
-  for (const key of FORWARD_VARS) {
-    const value = process.env[key];
-    if (value) {
-      flags.push('-e', `${key}=${value}`);
+  const spec = resolveModelSpec();
+  const providerVars = typeof spec === 'string' ? [] : providerForwardVars(spec.providerId);
+
+  for (const key of [...COMMON_FORWARD_VARS, ...providerVars]) {
+    if (process.env[key]) {
+      flags.push('-e', key);
     }
   }
 
@@ -57,71 +109,91 @@ export function buildEnvFlags(): string[] {
 interface CredentialValidation {
   valid: boolean;
   error?: string;
-  mode: 'api-key' | 'oauth' | 'custom-base-url' | 'bedrock';
 }
 
-/** Check if a custom Anthropic-compatible base URL is configured. */
-function isCustomBaseUrlConfigured(): boolean {
-  return !!(process.env.ANTHROPIC_BASE_URL && process.env.ANTHROPIC_AUTH_TOKEN);
+/** 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.some((name) => Boolean(process.env[name]))) return false;
+  return PROVIDER_EXTRA_ENV[providerId].every((name) => Boolean(process.env[name]));
 }
 
-/** Detect which providers are configured via environment variables. */
-function detectProviders(): string[] {
-  const providers: string[] = [];
-  if (process.env.ANTHROPIC_API_KEY) providers.push('Anthropic API key');
-  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) providers.push('Anthropic OAuth');
-  if (isCustomBaseUrlConfigured()) providers.push('Custom Base URL');
-  if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') providers.push('AWS Bedrock');
-  return providers;
+/** 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));
 }
 
 /**
- * Validate that exactly one authentication method is configured.
+ * Validate that the model selection parses and its provider has a credential.
+ * Runs before any Docker work so mistakes fail immediately.
  */
 export function validateCredentials(): CredentialValidation {
-  // Reject multiple providers
-  const providers = detectProviders();
-  if (providers.length > 1) {
+  // 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 ${requirement} in .env or export it.`
+        : `Export the variables or run 'npx @keygraph/shannon setup'.`;
     return {
       valid: false,
-      mode: 'api-key',
-      error: `Multiple providers detected: ${providers.join(', ')}. Only one provider can be active at a time.`,
+      error: `No credentials found for provider "${spec.providerId}". ${hint}`,
     };
   }
 
-  if (process.env.ANTHROPIC_API_KEY) {
-    return { valid: true, mode: 'api-key' };
-  }
-  if (process.env.CLAUDE_CODE_OAUTH_TOKEN) {
-    return { valid: true, mode: 'oauth' };
-  }
-  if (isCustomBaseUrlConfigured()) {
-    return { valid: true, mode: 'custom-base-url' };
-  }
-  if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
-    const missing: string[] = [];
-    if (!process.env.AWS_REGION) missing.push('AWS_REGION');
-    if (!process.env.AWS_BEARER_TOKEN_BEDROCK) missing.push('AWS_BEARER_TOKEN_BEDROCK');
-    if (!process.env.ANTHROPIC_SMALL_MODEL) missing.push('ANTHROPIC_SMALL_MODEL');
-    if (!process.env.ANTHROPIC_MEDIUM_MODEL) missing.push('ANTHROPIC_MEDIUM_MODEL');
-    if (!process.env.ANTHROPIC_LARGE_MODEL) missing.push('ANTHROPIC_LARGE_MODEL');
-    if (missing.length > 0) {
-      return {
-        valid: false,
-        mode: 'bedrock',
-        error: `Bedrock mode requires: ${missing.join(', ')}`,
-      };
+  // 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.
+  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: true, mode: 'bedrock' };
+    return { valid: false, error: lines.join('\n') };
   }
 
-  const hint =
-    getMode() === 'local'
-      ? `No credentials found. Set ANTHROPIC_API_KEY in .env or export it.`
-      : `Authentication not configured. Export variables or run 'npx @keygraph/shannon setup'.`;
-  return {
-    valid: false,
-    mode: 'api-key',
-    error: hint,
-  };
+  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

@@ -1,5 +1,5 @@
 /**
- * Shannon CLI — AI Penetration Testing Framework
+ * Shannon CLI — AI Pentester for Web Apps and APIs
  *
  * Unified CLI supporting two modes:
  *   Local mode: Run from cloned repo — builds locally, mounts prompts, uses ./workspaces/
@@ -9,15 +9,21 @@
  * 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, type Mode } from './mode.js';
+import { displaySplash } from './splash.js';
+import { closestMatch } from './suggest.js';
+import { stdoutIsTerminal } from './tty.js';
 import { getVersion, getVersionLine } from './version.js';
 
 function blockSudo(): void {
@@ -25,69 +31,73 @@ 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');
+}
+
+/**
+ * Render the command list with the description column aligned. Padding is computed from the
+ * widest command, so it lines up regardless of the prefix (`npx @keygraph/shannon` vs `./shannon`).
+ */
+function renderUsage(prefix: string, mode: Mode): string {
+  const rows: ReadonlyArray<readonly [string, string]> = [
+    ...(mode === 'local' ? [] : [[`${prefix} setup`, 'Configure credentials'] as const]),
+    [`${prefix} start --url <url> --repo <path> [options]`, 'Start a pentest scan'],
+    [`${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 <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'] as const] : []),
+    [`${prefix} version [--json]`, 'Show version'],
+    [`${prefix} help`, 'Show this help'],
+  ];
+
+  const commandWidth = Math.max(...rows.map(([command]) => command.length));
+  return rows.map(([command, desc]) => `  ${command.padEnd(commandWidth)}   ${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 Pentester by Keygraph\n';
 
-Usage:${
-    mode === 'local'
-      ? ''
-      : `
-  ${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} logs <workspace>                             Show a scan's live log
-  ${prefix} status                                       Show running scans${
-    mode === 'local'
-      ? `
-  ${prefix} build [--no-cache]                           Build worker image`
-      : `
-  ${prefix} uninstall [--yes]                            Remove ~/.shannon/ and all data`
-  }
-  ${prefix} version                                      Show version
-  ${prefix} help                                         Show this help
+  console.log(`${header}
+Usage:
+${renderUsage(prefix, mode)}
 
 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 +108,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 && stdoutIsTerminal()) 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'));
-    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/log-render.ts

@@ -0,0 +1,167 @@
+/**
+ * Decorates a tailed workflow.log for the terminal.
+ *
+ * The worker writes workflow.log as plain text and the CLI reads it back, so all of the
+ * chrome lives here on the read side. Nothing in this file changes what the log *says* —
+ * it adds the section treatments the plain file has no way to carry:
+ *
+ *   the log header and RESUMED banner  ->  rule()    (their ==== bars become the rule)
+ *   everything between phases          ->  gutter()  (one bar per phase, walking the ramp)
+ *   the closing Scan COMPLETED block   ->  panel()   (its ==== bars become the frame)
+ *
+ * When stdout is not a terminal the renderer is a pass-through and emits the file's bytes
+ * unchanged, so redirected logs, pipes, and CI keep grepping the same text they always did.
+ */
+
+import { field, gutter, palette, panel, rule } from './chrome.js';
+
+/** The ==== bars that open and close a block; replaced by our own chrome. */
+const BLOCK_BAR = /^={10,}\s*$/;
+
+/** The ──── bar dividing a block's title from its body; replaced by the panel frame. */
+const INNER_BAR = /^─{10,}\s*$/;
+
+/** `[2026-08-26 17:04:11] ` — every streamed event line carries one. */
+const TIMESTAMP = /^(\[\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}\])( .*)$/;
+
+/** A phase transition opens a new gutter section. */
+const PHASE_START = /^\[[^\]]*\] \[PHASE\] Starting: /;
+
+/** Titles of the two banner blocks, which take the static rule treatment. */
+const BANNER_TITLE = /^(Shannon Pentest - Scan Log|RESUMED)$/;
+
+/** Title of the final block, which takes the panel treatment. Mirrors logs.ts's completion regex. */
+const COMPLETION_TITLE = /^Scan (COMPLETED|FAILED)$/;
+
+/** Dim the timestamp so the message reads first; errors take the semantic red, not a ramp colour. */
+function colorizeEvent(line: string): string {
+  const { DIM, RED, RESET } = palette();
+  const match = TIMESTAMP.exec(line);
+  if (!match) return line;
+  const rest = match[2] ?? '';
+  const body = rest.includes('[ERROR]') ? `${RED}${rest}${RESET}` : rest;
+  return `${DIM}${match[1]}${RESET}${body}`;
+}
+
+type Mode = 'stream' | 'banner' | 'summary';
+
+export class LogRenderer {
+  /** Bytes past the last newline, held until the rest of the line arrives. */
+  private carry = '';
+  private mode: Mode = 'stream';
+  /** Suppresses a second consecutive blank line; starts true so the stream can't open on one. */
+  private lastBlank = true;
+  /** Current sunset stop for the gutter bar; advanced by each phase transition. */
+  private stop = 0;
+  private summaryTitle = '';
+  private summaryBody: string[] = [];
+  private readonly passthrough: boolean;
+
+  constructor() {
+    this.passthrough = !palette().color;
+  }
+
+  /** Decorate a chunk of newly appended log text. Incomplete trailing lines are held back. */
+  write(chunk: string): string {
+    if (this.passthrough) return chunk;
+
+    const text = this.carry + chunk;
+    const lines = text.split('\n');
+    // The final element is whatever followed the last newline — possibly a partial line.
+    this.carry = lines.pop() ?? '';
+
+    const out: string[] = [];
+    for (const line of lines) {
+      out.push(...this.renderLine(line));
+    }
+    return this.emit(out);
+  }
+
+  /** Join rendered lines, dropping blank runs left behind by the bars we removed. */
+  private emit(lines: string[]): string {
+    const kept: string[] = [];
+    for (const line of lines) {
+      const blank = line === '';
+      if (blank && this.lastBlank) continue;
+      this.lastBlank = blank;
+      kept.push(line);
+    }
+    return kept.length ? `${kept.join('\n')}\n` : '';
+  }
+
+  /** Flush a held partial line and close an unterminated summary block. */
+  end(): string {
+    if (this.passthrough) return '';
+
+    const out: string[] = [];
+    if (this.carry) {
+      out.push(...this.renderLine(this.carry));
+      this.carry = '';
+    }
+    if (this.mode === 'summary') {
+      out.push(...this.closeSummary());
+    }
+    return this.emit(out);
+  }
+
+  private renderLine(raw: string): string[] {
+    // Strip the \r from CRLF logs so it never lands in the middle of a decorated line.
+    const line = raw.endsWith('\r') ? raw.slice(0, -1) : raw;
+
+    // Only a ==== bar closes the summary; its ──── divider is chrome we replace, not a terminator.
+    if (BLOCK_BAR.test(line)) {
+      return this.mode === 'summary' ? this.closeSummary() : [];
+    }
+    if (INNER_BAR.test(line)) return [];
+
+    if (COMPLETION_TITLE.test(line)) {
+      this.mode = 'summary';
+      this.summaryTitle = line;
+      this.summaryBody = [];
+      return [''];
+    }
+
+    if (BANNER_TITLE.test(line)) {
+      this.mode = 'banner';
+      return ['', rule(line)];
+    }
+
+    if (this.mode === 'summary') {
+      this.summaryBody.push(line);
+      return [];
+    }
+
+    if (this.mode === 'banner') {
+      // The banner runs until the first streamed event.
+      if (!TIMESTAMP.test(line)) {
+        return [line.trim() ? `    ${field(line)}` : ''];
+      }
+      this.mode = 'stream';
+    }
+
+    // A blank line separates sections; the bar resumes on the next line of content.
+    if (!line.trim()) return [''];
+
+    if (PHASE_START.test(line)) {
+      // Two stops per phase, not one: the 256-colour tier collapses the seven stops into
+      // four xterm colours, and a single step would give consecutive phases the same bar.
+      // Seven is odd, so a stride of two still visits every stop before repeating.
+      this.stop += 2;
+    }
+    return [gutter(colorizeEvent(line), this.stop)];
+  }
+
+  private closeSummary(): string[] {
+    const title = this.summaryTitle;
+    const body = [...this.summaryBody];
+    while (body.length && !body[body.length - 1]?.trim()) body.pop();
+    while (body.length && !body[0]?.trim()) body.shift();
+
+    this.mode = 'stream';
+    this.summaryTitle = '';
+    this.summaryBody = [];
+
+    const rows = body.map((line) => (line.trim() ? field(line) : ''));
+    return [...panel(title, rows), ''];
+  }
+}

apps/cli/src/mode.ts

@@ -23,3 +23,12 @@ export function setMode(mode: Mode): void {
 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

@@ -0,0 +1,91 @@
+/**
+ * Parsing for the single model setting, `SHANNON_AI_MODEL=<provider>:<model-id>`.
+ *
+ * Mirrors apps/worker/src/ai/models.ts. The CLI cannot import from the worker
+ * package (it ships as a standalone bundle), so the provider list and the parse
+ * rule are duplicated here deliberately and must stay in sync.
+ */
+
+/**
+ * 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 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 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<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 curated provider requires beyond its API key. All must be set. */
+export const PROVIDER_EXTRA_ENV: Readonly<Record<CuratedProviderId, readonly string[]>> = {
+  anthropic: [],
+  openai: [],
+  xai: [],
+  'amazon-bedrock': ['AWS_REGION'],
+};
+
+/** Human-readable credential requirement, used in "nothing configured" errors. */
+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',
+  'amazon-bedrock': 'AWS_REGION and AWS_BEARER_TOKEN_BEDROCK',
+};
+
+/** Model used when SHANNON_AI_MODEL is unset. */
+export const DEFAULT_MODEL_SPEC = 'anthropic:claude-sonnet-4-6';
+
+/**
+ * Values SHANNON_AI_OPENAI_FORMAT accepts, selecting the wire format an
+ * OpenAI-compatible gateway serves. Mirrors OPENAI_FORMATS in
+ * apps/worker/src/ai/models.ts; the worker validates and applies it.
+ */
+export const OPENAI_FORMATS = ['chat-completions', 'responses'] as const;
+
+export type OpenAiFormat = (typeof OPENAI_FORMATS)[number];
+
+export interface ModelSpec {
+  providerId: string;
+  modelId: string;
+}
+
+/**
+ * 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`).
+ * 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();
+  const separator = trimmed.indexOf(':');
+  const malformed = `SHANNON_AI_MODEL must be "<provider>:<model-id>", got "${trimmed}". Example: ${DEFAULT_MODEL_SPEC}`;
+  if (separator === -1) return malformed;
+
+  const providerId = trimmed.slice(0, separator).trim();
+  const modelId = trimmed.slice(separator + 1).trim();
+  if (!providerId || !modelId) return malformed;
+
+  return { providerId, modelId };
+}
+
+/** Resolve the run's model spec from the environment, or an error string. */
+export function resolveModelSpec(): ModelSpec | string {
+  return parseModelSpec(process.env.SHANNON_AI_MODEL || DEFAULT_MODEL_SPEC);
+}

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/failure.ts

@@ -0,0 +1,31 @@
+/**
+ * Rendering for the worker's '|'-delimited failure string.
+ *
+ * `formatWorkflowError` in the worker joins error segments — phase context, error type,
+ * message, and remediation hint — with '|' as a delimiter. These helpers turn that raw
+ * string into readable output for the CLI's own surfaces.
+ */
+
+/**
+ * Split the failure string into trimmed, non-empty lines. Segments are delimited by '|', and a
+ * segment's own embedded newlines (e.g. a multi-line validation message) become their own lines so
+ * each aligns with the rest of the block.
+ */
+export function parseFailureSegments(message: string): string[] {
+  return message
+    .split(/[|\n]/)
+    .map((segment) => segment.trim())
+    .filter((segment) => segment.length > 0);
+}
+
+/** Multi-line block: one segment per indented line (the caller prints the header). */
+export function indentFailureSegments(message: string, indent = '  '): string {
+  return parseFailureSegments(message)
+    .map((segment) => `${indent}${segment}`)
+    .join('\n');
+}
+
+/** Single-line summary for compact contexts like the status footer. */
+export function inlineFailureReason(message: string): string {
+  return parseFailureSegments(message).join(' — ');
+}

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,250 @@
+/**
+ * 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 { inlineFailureReason } from './failure.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 rawReason = input.failureMessage ?? input.state?.error;
+    const reason = rawReason ? inlineFailureReason(rawReason) : '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

@@ -3,52 +3,66 @@
  * Color escapes are gated on terminal support; the Unicode art is always kept.
  */
 
-import { supportsColor } from './tty.js';
+import { palette } from './chrome.js';
+
+/** SHANNON wordmark. Block glyphs take the row fill; box-drawing strokes take the deeper edge shade. */
+const SHANNON = [
+  '███████╗██╗  ██╗ █████╗ ███╗   ██╗███╗   ██╗ ██████╗ ███╗   ██╗',
+  '██╔════╝██║  ██║██╔══██╗████╗  ██║████╗  ██║██╔═══██╗████╗  ██║',
+  '███████╗███████║███████║██╔██╗ ██║██╔██╗ ██║██║   ██║██╔██╗ ██║',
+  '╚════██║██╔══██║██╔══██║██║╚██╗██║██║╚██╗██║██║   ██║██║╚██╗██║',
+  '███████║██║  ██║██║  ██║██║ ╚████║██║ ╚████║╚██████╔╝██║ ╚████║',
+  '╚══════╝╚═╝  ╚═╝╚═╝  ╚═╝╚═╝  ╚═══╝╚═╝  ╚═══╝ ╚═════╝ ╚═╝  ╚═══╝',
+];
 
 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 RESET = color ? '\x1b[0m' : '';
+  const { color, RESET, WHITE, GRAY, DIM, ramp } = palette();
 
-  const B = `${CYAN}\u2551${RESET}`;
-  const S67 = ' '.repeat(67);
-  const HR = '\u2550'.repeat(67);
+  /** 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'));
 }
+
+/** Matches the divider width the CI wrappers and the scan renderer already use. */
+const RULE_WIDTH = 60;
+
+/**
+ * Plain-text banner for non-terminal output (CI logs, pipes, redirects).
+ * Drops the wordmark but keeps the authorized-use notice, which a reader of
+ * someone else's pipeline log still needs to see.
+ */
+export function displayPlainBanner(version?: string): void {
+  const rule = '─'.repeat(RULE_WIDTH);
+  console.log(rule);
+  console.log(version ? ` Shannon v${version}` : ' Shannon');
+  console.log(' AI Pentester for Web Apps and APIs, by Keygraph');
+  console.log(' Authorized security testing only.');
+  console.log(rule);
+}

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,200 @@
+/**
+ * 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 { setTimeout as sleep } from 'node:timers/promises';
+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';
+
+// WorkflowExecutionStatusName values that mean the scan has closed. RUNNING (and the unused
+// CONTINUED_AS_NEW) are the only non-terminal states.
+const TERMINAL_STATUSES: ReadonlySet<string> = new Set(['COMPLETED', 'FAILED', 'CANCELLED', 'TERMINATED', 'TIMED_OUT']);
+
+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;
+}
+
+/** How a {@link waitForWorkflowClose} watch ended. */
+export type WatchEnd = { readonly reason: 'closed' } | { readonly reason: 'unreachable'; readonly lastError: string };
+
+export interface WatchOptions {
+  /** Poll interval in ms (default 3000). */
+  readonly pollMs?: number;
+  /** Consecutive connection failures before giving up (default 10 → ~30s at the default interval). */
+  readonly maxConnectFailures?: number;
+  /** Consecutive connection failures before {@link onConnectionTrouble} fires once (default 3). */
+  readonly warnAfterFailures?: number;
+  /** Abort the watch (the caller stopped for another reason, e.g. Ctrl-C). */
+  readonly signal?: AbortSignal;
+  /** Called once when contact is first lost, so a live follower's log isn't silent during the outage. */
+  readonly onConnectionTrouble?: (lastError: string) => void;
+  /** Called once when contact is regained after {@link onConnectionTrouble} fired. */
+  readonly onReconnected?: () => void;
+}
+
+/**
+ * Resolve once the scan is no longer running, using the workflow's Temporal status as the
+ * completion signal. Ends on a terminal status, a not-found workflow (closed past retention), or
+ * maxConnectFailures consecutive unreachable polls (a scan can't progress while its Temporal is
+ * down, so sustained no-contact is a safe stop). Never rejects; connection errors surface via the
+ * callbacks and the returned {@link WatchEnd}.
+ */
+export async function waitForWorkflowClose(workflowId: string, opts: WatchOptions = {}): Promise<WatchEnd> {
+  const pollMs = opts.pollMs ?? 3000;
+  const maxConnectFailures = opts.maxConnectFailures ?? 10;
+  const warnAfterFailures = opts.warnAfterFailures ?? 3;
+  const signal = opts.signal;
+
+  let connectFailures = 0;
+  let lastError = '';
+  let warned = false;
+
+  while (!signal?.aborted) {
+    try {
+      const desc = await describeScan(workflowId);
+      if (desc === null || TERMINAL_STATUSES.has(desc.status)) {
+        return { reason: 'closed' };
+      }
+      // Reachable and still RUNNING — reset the failure streak and note any recovery.
+      if (warned) {
+        warned = false;
+        opts.onReconnected?.();
+      }
+      connectFailures = 0;
+    } catch (err) {
+      connectFailures++;
+      lastError = err instanceof Error ? err.message : String(err);
+      if (!warned && connectFailures >= warnAfterFailures) {
+        warned = true;
+        opts.onConnectionTrouble?.(lastError);
+      }
+      if (connectFailures >= maxConnectFailures) {
+        return { reason: 'unreachable', lastError };
+      }
+    }
+
+    try {
+      await sleep(pollMs, undefined, { signal });
+    } catch {
+      break; // Aborted mid-wait by the caller.
+    }
+  }
+
+  return { reason: 'closed' };
+}
+
+/** 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

@@ -102,23 +102,6 @@
       "required": ["login_type", "login_url", "credentials", "success_condition"],
       "additionalProperties": false
     },
-    "pipeline": {
-      "type": "object",
-      "description": "Pipeline execution settings for retry behavior and concurrency",
-      "properties": {
-        "retry_preset": {
-          "type": "string",
-          "enum": ["default", "subscription"],
-          "description": "Retry preset. 'subscription' extends timeouts for Anthropic subscription rate limit windows (5h+)."
-        },
-        "max_concurrent_pipelines": {
-          "type": "string",
-          "pattern": "^[1-5]$",
-          "description": "Max concurrent vulnerability pipelines (1-5, default: 5)"
-        }
-      },
-      "additionalProperties": false
-    },
     "rules": {
       "type": "object",
       "description": "Testing rules that define what to focus on or avoid during penetration testing",
@@ -177,6 +160,11 @@
           "minLength": 1,
           "maxLength": 500,
           "description": "Free-text guidance to the report agent (e.g., 'Drop findings about missing security headers')."
+        },
+        "sarif": {
+          "type": "string",
+          "enum": ["true", "false"],
+          "description": "Emit a SARIF 2.1.0 log (report.sarif) beside the report. On by default for exploit runs; set \"false\" to opt out. Ignored when exploit=false."
         }
       },
       "additionalProperties": false
@@ -218,7 +206,6 @@
       "properties": {
         "description": {
           "type": "string",
-          "minLength": 1,
           "maxLength": 200,
           "description": "Human-readable description of the rule"
         },
@@ -234,7 +221,7 @@
           "description": "Value to match"
         }
       },
-      "required": ["description", "type", "value"],
+      "required": ["type", "value"],
       "additionalProperties": false
     }
   }

apps/worker/configs/example-config.yaml

@@ -96,13 +96,11 @@ rules:
 # Report filters applied by the report agent when assembling the final report (optional).
 # Example below is illustrative; edit, remove, or add sections as needed.
 # report:
+#   # SARIF 2.1.0 log (report.sarif) beside the report. On by default for exploit runs;
+#   # set "false" to opt out. Ignored when exploit is "false".
+#   sarif: "false"
 #   min_severity: low
 #   min_confidence: low
 #   guidance: |
 #     Drop findings about missing security headers and rate-limit gaps.
 #     ...
-
-# Pipeline execution settings (optional)
-# pipeline:
-#   retry_preset: subscription          # 'default' or 'subscription' (6h max retry for rate limit recovery)
-#   max_concurrent_pipelines: 2         # 1-5, default: 5 (reduce to lower API usage spikes)

apps/worker/package.json

@@ -19,9 +19,9 @@
     "clean": "rm -rf dist"
   },
   "dependencies": {
-    "@earendil-works/pi-agent-core": "^0.79.1",
-    "@earendil-works/pi-ai": "^0.79.1",
-    "@earendil-works/pi-coding-agent": "^0.79.1",
+    "@earendil-works/pi-agent-core": "^0.84.2",
+    "@earendil-works/pi-ai": "^0.84.2",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
     "@gotgenes/pi-permission-system": "^10.9.0",
     "@temporalio/activity": "^1.11.0",
     "@temporalio/client": "^1.11.0",

apps/worker/prompts/report-executive.txt

@@ -1,112 +1,198 @@
 <role>
-You are an Executive Summary Writer and Report Cleaner for security assessments. Your job is to:
-1. MODIFY the existing concatenated report by adding an executive summary at the top
-2. CLEAN UP hallucinated or extraneous sections throughout the report
+<exploit_mode_role>
+You are the Security Report Writer for a multi-agent security assessment pipeline. Upstream agents have already explored the target application, generated security hypotheses, and verified them by exploitation. Your job is to synthesize the verified findings into structured data that downstream renderers will use to produce reports and persist to the database.
+</exploit_mode_role>
+<analysis_mode_role>
+You are the Security Report Writer for a multi-agent security assessment pipeline. Upstream agents have explored the target application, generated security hypotheses, and assessed them against the source code. Your job is to synthesize those findings into structured data that downstream renderers will use to produce reports and persist to the database.
+</analysis_mode_role>
 </role>
 
-<audience>
-Technical leadership (CTOs, CISOs, Engineering VPs) who need both technical accuracy and executive brevity.
-</audience>
+<task>
+Record all findings as structured data using the `add_finding` tool. You do NOT write a markdown report — a downstream renderer produces the report from your structured output.
 
-<objective>
-The orchestrator has already concatenated all per-class deliverables into `comprehensive_security_assessment_report.md`. Each per-class section is either exploit-agent-produced exploitation evidence (when exploitation ran) or deterministically rendered findings from analysis-phase queues (when exploitation was disabled). The cleanup rules below apply uniformly to either source.
-Your task is to:
-1. Read this existing concatenated report
-2. Add an Executive Summary (vulnerability overview) at the top
-3. Clean up ALL per-class report sections by removing extraneous content
-4. Save the modified version back to the same file
+1. **Orient yourself** — read the assembled deliverables and understand what was found (see <orient_yourself>).
+2. **Filter and clean** — identify real findings, remove noise, rewrite weak titles (see <filter_and_clean>).
+3. **Record report metadata** — run `set-report-meta` once (see <record_report_meta>).
+4. **Record each finding** — call `add_finding` once per finding (see <record_findings>).
+</task>
 
-IMPORTANT: You are MODIFYING an existing file, not creating a new one.
-</objective>
+<tools_reference>
+You have two tools for recording findings:
 
-<target>
-URL: {{WEB_URL}}
+- **set-report-meta** (CLI via `bash`) — Write top-level report metadata. Call once before recording findings.
+  `set-report-meta --target "https://..." --assessment-date "YYYY-MM-DD" --scope "..." --executive-summary "..."`
+  Returns: `{"status":"success"}`
+  Shell quoting: wrap flag values in double quotes. Escape any literal double quotes as \", dollar signs as \$, and backticks as \`.
 
-Filesystem:
-- {{REPO_PATH}}/ (read only)
-- {{REPO_PATH}}/.shannon/deliverables/ (read-write)
-- {{REPO_PATH}}/.shannon/scratchpad/ (read-write) - screenshots, scripts, scratch work, etc.
-</target>
+- **add_finding** (tool) — Record a single finding as structured data. Call once per finding. Rejects duplicate finding_ids. The tool schema describes all required and optional fields — fill them in directly.
+</tools_reference>
 
-<context>
-Authentication Context:
-{{AUTH_CONTEXT}}
+<orient_yourself>
+Before recording anything, read and understand your inputs.
 
-Vulnerability classes tested in this run: {{VULN_CLASSES_TESTED}}
+### Your goal
+<exploit_mode_orient>
+You are the final agent in the pipeline. Upstream agents have already performed reconnaissance, analyzed vulnerabilities, and exploited them. Their evidence has been assembled into a concatenated report. Your job is to read that report, identify the real findings, and emit each one as structured data via the `add_finding` tool.
+</exploit_mode_orient>
+<analysis_mode_orient>
+You are the final agent in the pipeline. Upstream agents have performed reconnaissance and analyzed vulnerabilities in the source code. **No exploitation phase ran** — nothing was executed against the target and no vulnerability was confirmed by attack. Their analysis has been assembled into a concatenated report. Your job is to read that report, identify the real findings, and emit each one as structured data via the `add_finding` tool.
+</analysis_mode_orient>
+
+### Your inputs
+Read these files:
+- `.shannon/deliverables/comprehensive_security_assessment_report.md` — The concatenated per-class deliverables. This is your primary input. Each per-class section contains vulnerability entries with IDs.
+- `.shannon/deliverables/pre_recon_deliverable.md` — Initial reconnaissance and technology stack (for executive summary context).
+- `.shannon/deliverables/recon_deliverable.md` — Attack surface mapping and endpoint discovery (for executive summary context).
+
+### Vulnerability ID patterns
+Findings have IDs matching `[TYPE]-VULN-[NUMBER]` (e.g., INJ-VULN-01, AUTH-VULN-03).
+
+### Context
+Target URL: {{WEB_URL}}
+Vulnerability classes tested: {{VULN_CLASSES_TESTED}}
 Exploitation: {{EXPLOITATION}}
-</context>
+{{AUTH_CONTEXT}}
+</orient_yourself>
+
+{{NOT_ASSESSED_CLASSES}}
 
 {{REPORT_FILTERS_BLOCK}}
 
-<input_files>
-You will analyze the following deliverable files:
-- `.shannon/deliverables/pre_recon_deliverable.md` - Initial reconnaissance and technology stack
-- `.shannon/deliverables/recon_deliverable.md` - Attack surface mapping and endpoint discovery
-- `.shannon/deliverables/comprehensive_security_assessment_report.md` - The already-concatenated report that you will modify
-</input_files>
+<filter_and_clean>
+Read through the concatenated report and identify which vulnerability entries to record. Apply these rules:
 
-<deliverable_instructions>
-MODIFY the existing file `.shannon/deliverables/comprehensive_security_assessment_report.md` by:
-
-1. ADDING these sections at the top:
-
-# Security Assessment Report
-
-## Executive Summary
-- Target: {{WEB_URL}}
-- Assessment Date: {current date}
-- Scope: {{VULN_CLASSES_TESTED}}
-- Exploitation: {{EXPLOITATION}}
-
-## Summary by Vulnerability Type
-
-{For each vulnerability type below, examine the comprehensive_security_assessment_report.md sections and provide a summary. If no section exists for that type or no vulnerabilities are listed, explicitly state that none were found.}
-
-{{VULN_SUMMARY_SUBSECTIONS}}
-
-2. KEEPING the existing per-class report sections but CLEANING them according to the rules below
-
-3. The final structure should be:
-   - Executive Summary (new)
-   - All existing per-class report sections (cleaned)
-
-IMPORTANT: Do NOT reorder the existing per-class report sections. Maintain the exact order they appear in the concatenated report. Only remove sections that do not match the defined criteria above.
-
-</deliverable_instructions>
-
-<instructions>
-1. Read the pre_recon and recon deliverable files to gather security-relevant information:
-   - Skip basic information such as technology stack information (the team knows their own stack)
-   - Use technical leadership tone - precise but concise
-   - Use the current date for the assessment date
-
-2. Create the Executive Summary content:
-   - Executive Summary: Technical overview with actionable findings for engineering leaders
-
-3. Clean the per-class report sections in `.shannon/deliverables/comprehensive_security_assessment_report.md` by applying these rules:
-   - KEEP these specific section headings:
-     NOTE: these sections will contain vulnerability lists with IDs matching pattern `### [TYPE]-VULN-[NUMBER]`
-     * `# [Type] {{REPORT_VULN_HEADING}}`
-     * `## {{REPORT_VULN_SUBHEADING}}`
+### KEEP — these are real findings to record via `add_finding`
+- Vulnerability entries under `## {{REPORT_VULN_SUBHEADING}}` sections with IDs matching `### [TYPE]-VULN-[NUMBER]`
 {{REPORT_FILTER_RULES}}
-   - REMOVE ANY OTHER SECTIONS (even if they contain vulnerability IDs), such as:
-     * `## Potential Vulnerabilities (Validation Blocked)` (All agents)
-     * Standalone "Recommendations" sections
-     * "Conclusion" sections
-     * "Summary" sections
-     * "Next Steps" sections
-     * "Additional Analysis" sections
-     * Any other meta-commentary sections without vulnerability IDs
-     * False positives sections
-     * any intros in the sections
-     * any counts in the sections
-   - Preserve exact vulnerability IDs (`### [TYPE]-VULN-NN:`); if the title after the colon is only a short category label rather than a descriptive phrase, rewrite it to a concise human-readable descriptor derived from the finding's Vulnerable location and Overview.
 
-4. Combine the content:
-   - Place the Executive Summary and Network Reconnaissance sections at the top
-   - Follow with the cleaned per-class report sections
-   - Save as the modified `.shannon/deliverables/comprehensive_security_assessment_report.md`
+### SKIP — do not record these
+<exploit_mode_skip>
+- `## Potential Vulnerabilities (Validation Blocked)` entries
+</exploit_mode_skip>
+- Standalone "Recommendations", "Conclusion", "Summary", "Next Steps", "Additional Analysis" sections
+- False positives sections
+- Introductory text, vulnerability counts, or meta-commentary without vulnerability IDs
+- Any section that does not contain a finding with a valid vulnerability ID
 
-CRITICAL: You are modifying the existing concatenated report at `.shannon/deliverables/comprehensive_security_assessment_report.md` IN-PLACE, not creating a separate file.
-</instructions>
+### Title cleanup
+If a finding's title (the text after the colon in `### TYPE-VULN-NN: Title`) is only a short category label rather than a descriptive phrase, rewrite it to a concise descriptor derived from the finding's "Vulnerable location" and "Overview" fields. Use the improved title when calling `add_finding`.
+</filter_and_clean>
 
+<record_report_meta>
+Run `set-report-meta` once before recording any individual findings (see <tools_reference> for usage).
+
+Fields:
+- `target`: `{{WEB_URL}}`
+- `assessment_date`: Use the current date in ISO format (YYYY-MM-DD)
+- `scope`: `{{VULN_CLASSES_TESTED}}`
+<exploit_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 — 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 — 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>
+
+<record_findings>
+For each finding identified in <filter_and_clean>, call `add_finding` once.
+
+Record findings in the order they appear in the concatenated report (which groups by vulnerability class: injection, xss, auth, ssrf, authz).
+
+Each `finding_id` may only be recorded once — duplicate calls are rejected.
+
+### How to fill in each field
+
+Map the finding's content from the per-class deliverable sections to `add_finding` fields:
+
+- `finding_id`: The vulnerability ID exactly as it appears (e.g., `"INJ-VULN-01"`, `"AUTH-VULN-07"`)
+- `title`: The cleaned-up title (see title cleanup rules in <filter_and_clean>)
+- `category`: Derived from the finding type prefix — `INJ` → `"Injection"`, `XSS` → `"XSS"`, `AUTH` → `"Authentication"`, `AUTHZ` → `"Authorization"`, `SSRF` → `"SSRF"`
+<exploit_mode_fields>
+- `severity`: From the finding's "Severity" field. Use as-is; do not reassess.
+</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"`
+  - `"A02:2025 — Security Misconfiguration"`
+  - `"A03:2025 — Software Supply Chain Failures"`
+  - `"A04:2025 — Cryptographic Failures"`
+  - `"A05:2025 — Injection"`
+  - `"A06:2025 — Insecure Design"`
+  - `"A07:2025 — Authentication Failures"`
+  - `"A08:2025 — Software or Data Integrity Failures"`
+  - `"A09:2025 — Security Logging and Alerting Failures"`
+  - `"A10:2025 — Mishandling of Exceptional Conditions"`
+- `vulnerable_location`: From the finding's "Vulnerable location" field
+- `http_location`: The HTTP request the finding is reached through, when the deliverable names one (e.g. `"GET /api/products?id="` gives `method: "GET"`, `url: "{{WEB_URL}}/api/products"`, `parameter: "id"`). Omit for findings with no network entry point.
+- `overview`: Synthesize from the finding's "Overview" field into professional prose. Do not paste verbatim.
+- `remediation`: Specific, actionable fix guidance from the finding. Code-level or configuration-level. Avoid generic advice.
+<exploit_mode_fields>
+- `impact`: From the finding's "Impact" field if present, otherwise derive from the overview and proof of impact
+- `auth_state`: From the finding's authentication context or prerequisites
+- `prerequisites`: From the finding's "Prerequisites" field, or `"None"` if not specified
+- `exploitation_steps`: From the finding's exploitation steps or proof-of-concept. Each step gets a title and ordered prose/code items. Use `"bash"` for shell commands, `"http"` for raw HTTP, `"json"` for response bodies.
+- `proof_of_impact`: From the finding's "Proof of Impact" or evidence section. What the exploit demonstrably achieved.
+- `status`: Optional. Use `"exploited"` for confirmed exploits.
+</exploit_mode_fields>
+<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 `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:**
+- `notes`: From the finding's "Notes" section if present
+- `additional_sections`: Any extra subsections on the finding that don't fit the fields above
+
+### Zero findings
+
+If no valid findings exist after filtering, do not call `add_finding` at all. The `set-report-meta` executive summary should state that no vulnerabilities were identified in the assessed classes. If a <not_assessed_classes> block is present, it must also state that those listed classes were not assessed.
+</record_findings>
+
+<constraints>
+<exploit_mode_constraints>
+- **No Fabrications:** Do not invent exploitation steps, evidence, or impact. Every piece of data must come from the deliverable files. If a finding has incomplete data, include it but note the gap in `overview`.
+- **No Severity Changes:** Use the severity from the deliverable as-is. Do not inflate or deflate.
+</exploit_mode_constraints>
+<analysis_mode_constraints>
+- **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.
+- **Remediation Quality:** Provide specific, actionable remediation — code-level or configuration-level fixes. Avoid generic advice like "validate input" or "follow best practices".
+</constraints>
+
+<self_check>
+Before finalizing, verify:
+
+- [ ] Did I run `set-report-meta` exactly once with target, assessment_date, scope, and executive_summary?
+- [ ] For each valid finding in the deliverables, did I call `add_finding` exactly once with the correct `finding_id`?
+<exploit_mode_skipcheck>
+- [ ] Did I skip all entries from "Potential Vulnerabilities (Validation Blocked)", false positives, and meta-commentary sections?
+</exploit_mode_skipcheck>
+<analysis_mode_skipcheck>
+- [ ] Did I skip false positives and meta-commentary sections?
+</analysis_mode_skipcheck>
+- [ ] Does every finding have a valid `owasp_category` using the 2025 categorization?
+- [ ] Does every finding have `overview`, `impact`, and `remediation`?
+<exploit_mode_checks>
+- [ ] Does every finding have `auth_state` and `prerequisites`?
+- [ ] Does every finding have `exploitation_steps` with prose/code items?
+- [ ] Does every finding have `proof_of_impact`?
+- [ ] Are severity ratings unchanged from the source deliverables?
+</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)?
+
+If any answer is NO, fix it before finalizing.
+</self_check>

apps/worker/prompts/vuln-auth.txt

@@ -100,7 +100,11 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 	  "missing_defense": "Concise description of the core problem (e.g., 'No rate limit on POST /login', 'Session ID not rotated after login').",
 	  "exploitation_hypothesis": "A clear statement describing the expected outcome of a successful exploit. This should describe an active attack outcome, not just vulnerability confirmation (e.g., 'An attacker can successfully log into an account by guessing a simple password,' 'An attacker can hijack a user's session by replaying a stolen cookie').",
 	  "suggested_exploit_technique": "The specific attack pattern to attempt, derived from the methodology. The exploitation agent should actively execute this attack, not just confirm it's possible (e.g., 'brute_force_login', 'credential_stuffing', 'session_hijacking', 'session_fixation').",
-	  "confidence": "High | Medium | Low",
+	  "confidence": "high | medium | low",
+	  "code_locations": [
+	    { "file": "lib/insecurity.ts", "start_line": 21, "role": "sink", "symbol": "verify" },
+	    { "file": "routes/login.ts", "start_line": 34, "role": "guard" }
+	  ],
 	  "notes": "Relevant details about required session state, applicable roles, observed headers, or links to related findings."
 	}
 </exploitation_queue_format>

apps/worker/prompts/vuln-authz.txt

@@ -107,7 +107,11 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 		"side_effect": "specific unauthorized action possible (e.g., 'read other users profiles', 'delete any file', 'skip payment')",
 		"reason": "1-2 lines explaining why this is vulnerable",
 		"minimal_witness": "brief description of how to trigger (e.g., 'change user_id param to another user', 'call admin endpoint as regular user')",
-		"confidence": "high | med | low",
+		"confidence": "high | medium | low",
+		"code_locations": [
+		  { "file": "server.ts", "start_line": 365, "role": "sink", "symbol": "getUserById" },
+		  { "file": "lib/insecurity.ts", "start_line": 92, "role": "guard" }
+		],
 		"notes": "any assumptions, related findings, or special conditions"
 	}
 </exploitation_queue_format>
@@ -220,7 +224,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
     - `guard_evidence` (missing/misplaced),
     - `side_effect` observed,
     - `reason` (1–2 lines: e.g., "ownership check absent"),
-    - `confidence` (high/med/low),
+    - `confidence` (high/medium/low),
     - `minimal_witness` (sketch for exploit agent).
 
 ---

apps/worker/prompts/vuln-injection.txt

@@ -111,7 +111,11 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 			"verdict": "safe | vulnerable.",
 			"mismatch_reason": "if vulnerable, 1–2 lines in plain language.",
 			"witness_payload": "minimal input you'd use later to show structure influence (e.g., ' for SQLi, ; ls -la for Command Injection, ../../../../etc/passwd for LFI, {{7*7}} for SSTI).",
-			"confidence": "high | med | low.",
+			"confidence": "high | medium | low",
+			"code_locations": [
+			  { "file": "routes/search.ts", "start_line": 42, "role": "sink", "symbol": "searchProducts" },
+			  { "file": "routes/search.ts", "start_line": 38, "role": "source" }
+			],
 			"notes": "assumptions, untraversed branches, anything unusual."
 		}
   </exploitation_queue_format>
@@ -164,7 +168,7 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 		    - `verdict` (`safe` / `vulnerable`)
 		    - `mismatch_reason` (plain-language, 1–2 lines)
 		    - `witness_payload` (minimal input to demonstrate structure influence — **for later exploit phase**)
-		    - `confidence` (`high` / `med` / `low`)
+		    - `confidence` (`high` / `medium` / `low`)
 		    - `notes` (assumptions, untraversed branches, unusual conditions)
   - **7) Score confidence**
     - **High:** binds on value/like/numeric; strict casts; whitelists for all syntax slots; **no** post-sanitization concat.

apps/worker/prompts/vuln-ssrf.txt

@@ -102,7 +102,11 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 	  "missing_defense": "Concise description of the core problem (e.g., 'No URL allowlist validation', 'Missing protocol restriction').",
 	  "exploitation_hypothesis": "A clear statement describing the expected outcome of a successful exploit (e.g., 'An attacker can access internal services by providing internal URLs', 'An attacker can retrieve cloud metadata through URL manipulation').",
 	  "suggested_exploit_technique": "The specific attack pattern to attempt, derived from the methodology (e.g., 'internal_service_access', 'cloud_metadata_retrieval', 'port_scanning', 'webhook_abuse').",
-	  "confidence": "High | Medium | Low",
+	  "confidence": "high | medium | low",
+	  "code_locations": [
+	    { "file": "routes/profileImageUrlUpload.ts", "start_line": 24, "role": "sink", "symbol": "profileImageUrlUpload" },
+	    { "file": "routes/profileImageUrlUpload.ts", "start_line": 18, "role": "source" }
+	  ],
 	  "notes": "Relevant details about request format, authentication requirements, observed timeouts, or links to related findings."
 	}
 </exploitation_queue_format>

apps/worker/prompts/vuln-xss.txt

@@ -108,7 +108,11 @@ Structure: The vulnerability JSON object MUST follow this exact format:
 		"verdict": "vulnerable | safe.",
 		"mismatch_reason": "If vulnerable, explain why the observed encoding is wrong for the render context (e.g., 'URL encoding used in an HTML attribute context, allowing event handler injection.').",
 		"witness_payload": "A minimal, non-malicious payload that proves context control (e.g., '><script>alert(1)</script>', '" onmouseover=alert(1) ').",
-		"confidence": "high | med | low.",
+		"confidence": "high | medium | low",
+		"code_locations": [
+		  { "file": "frontend/src/app/search-result/search-result.component.ts", "start_line": 121, "role": "sink", "symbol": "filterTable" },
+		  { "file": "frontend/src/app/search-result/search-result.component.ts", "start_line": 115, "role": "source" }
+		],
 		"notes": "Relevant CSP, HttpOnly flags, WAF behavior, or other environmental factors."
 	}
 </exploitation_queue_format>

apps/worker/src/ai/extensions/bash-timeout/index.ts

@@ -23,7 +23,7 @@ function evaluateBashTimeout(timeout: number | undefined): ToolCallEventResult |
   if (!hasValidTimeout) {
     return {
       block: true,
-      reason: `Set bash 'timeout' (seconds). Default ${DEFAULT_TIMEOUT_SECONDS}s, max ${MAX_TIMEOUT_SECONDS}s.`,
+      reason: `A timeout in seconds is required for the bash tool. The bash tool was not executed. Use the default of ${DEFAULT_TIMEOUT_SECONDS} seconds, or up to a maximum of ${MAX_TIMEOUT_SECONDS} seconds.`,
     };
   }
 

apps/worker/src/ai/models.ts

@@ -5,157 +5,338 @@
 // as published by the Free Software Foundation.
 
 /**
- * Model tier definitions and resolution for the pi harness.
+ * Model selection and resolution for the pi harness.
  *
- * Three tiers mapped to capability levels:
- * - "small"  (Haiku — summarization, structured extraction)
- * - "medium" (Sonnet — tool use, general analysis)
- * - "large"  (Opus — deep reasoning, complex analysis)
+ * One model runs the entire workflow. Users name it with a single setting:
  *
- * Users override per tier via ANTHROPIC_SMALL_MODEL / ANTHROPIC_MEDIUM_MODEL /
- * ANTHROPIC_LARGE_MODEL, which works across all providers (Anthropic, Bedrock,
- * custom base URL).
+ *   SHANNON_AI_MODEL=<provider>:<model-id>
  *
- * The active provider is chosen from the env-var contract the CLI forwards
- * (`CLAUDE_CODE_USE_BEDROCK`, `ANTHROPIC_BASE_URL`+`ANTHROPIC_AUTH_TOKEN`, else
- * direct Anthropic). Resolution returns a pi `Model` via `ModelRegistry.find`, the
- * `thinkingLevel`, and an `AuthStorage` primed with the right credential. Bedrock
- * authenticates from the AWS_ env vars via pi-ai.
+ * The provider half decides the endpoint, the credential, and the API dialect;
+ * the model half is passed to pi's registry as-is. The separator is a colon
+ * because model IDs routinely contain slashes, and it is the *first* colon that
+ * splits, because Bedrock model IDs contain colons of their own
+ * (`amazon-bedrock:us.anthropic.claude-opus-4-5-20251101-v1:0`).
+ *
+ * Resolution returns a pi `Model` plus the `ModelRuntime` that owns its auth,
+ * built over an in-memory credential store primed from the environment.
  */
 
-import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
-import type { Api, Model } from '@earendil-works/pi-ai';
-import { AuthStorage, type ModelRegistry } from '@earendil-works/pi-coding-agent';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import type { Api, Credential, CredentialInfo, CredentialStore, Model } from '@earendil-works/pi-ai';
+import { getAgentDir, ModelRuntime } from '@earendil-works/pi-coding-agent';
 
-export type ModelTier = 'small' | 'medium' | 'large';
+/**
+ * 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 CURATED_PROVIDERS = ['anthropic', 'openai', 'xai', 'amazon-bedrock'] as const;
 
-const DEFAULT_MODELS: Readonly<Record<ModelTier, string>> = {
-  small: 'claude-haiku-4-5-20251001',
-  medium: 'claude-sonnet-4-6',
-  large: 'claude-opus-4-8',
+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'],
+  'amazon-bedrock': ['AWS_BEARER_TOKEN_BEDROCK'],
 };
 
-export interface EffectiveProvider {
-  /** pi-ai provider id: 'anthropic' or 'amazon-bedrock'. */
+/** 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
+ * provider has exactly one API in pi's registry.
+ */
+export const OPENAI_FORMATS = {
+  'chat-completions': 'openai-completions',
+  responses: 'openai-responses',
+} as const;
+
+export type OpenAiFormat = keyof typeof OPENAI_FORMATS;
+
+/** Format assumed when a gateway is configured but no format is named. */
+export const DEFAULT_OPENAI_FORMAT: OpenAiFormat = 'chat-completions';
+
+function isOpenAiFormat(value: string): value is OpenAiFormat {
+  return value in OPENAI_FORMATS;
+}
+
+/**
+ * Read SHANNON_AI_OPENAI_FORMAT. Unset returns undefined, which lets the caller
+ * distinguish "not configured" from an explicit choice and reject the variable
+ * where it has no effect.
+ */
+export function resolveOpenAiFormat(): OpenAiFormat | undefined {
+  const raw = process.env.SHANNON_AI_OPENAI_FORMAT?.trim();
+  if (!raw) return undefined;
+
+  if (!isOpenAiFormat(raw)) {
+    throw new Error(
+      `SHANNON_AI_OPENAI_FORMAT must be one of: ${Object.keys(OPENAI_FORMATS).join(', ')}. Got "${raw}".`,
+    );
+  }
+  return raw;
+}
+
+export interface ModelSpec {
   providerId: string;
-  /** Custom-base-URL override applied to the resolved anthropic model. */
+  modelId: string;
+}
+
+/**
+ * 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();
+  const separator = trimmed.indexOf(':');
+  if (separator === -1) {
+    throw new Error(
+      `SHANNON_AI_MODEL must be "<provider>:<model-id>", got "${trimmed}". Example: ${DEFAULT_MODEL_SPEC}`,
+    );
+  }
+
+  const providerId = trimmed.slice(0, separator).trim();
+  const modelId = trimmed.slice(separator + 1).trim();
+
+  if (!providerId || !modelId) {
+    throw new Error(
+      `SHANNON_AI_MODEL must be "<provider>:<model-id>", got "${trimmed}". Example: ${DEFAULT_MODEL_SPEC}`,
+    );
+  }
+
+  return { providerId, modelId };
+}
+
+/** Resolve the run's model from SHANNON_AI_MODEL, falling back to the default. */
+export function resolveModelSpec(): ModelSpec {
+  return parseModelSpec(process.env.SHANNON_AI_MODEL || DEFAULT_MODEL_SPEC);
+}
+
+export interface ProviderCredentials {
+  /** Endpoint override, applied whatever the provider (proxies, gateways). */
   baseUrl?: string;
-  /** Runtime credential to prime on AuthStorage for the 'anthropic' provider. */
-  anthropicToken?: string;
+  /** Runtime API key primed into the ModelRuntime's credential store. */
+  apiKey?: string;
 }
 
 /**
- * Determine the active provider + auth from the env-var contract the CLI forwards:
- * `CLAUDE_CODE_USE_BEDROCK` → Bedrock; `ANTHROPIC_BASE_URL`+`ANTHROPIC_AUTH_TOKEN`
- * → custom base URL; else direct Anthropic (`ANTHROPIC_API_KEY`, or
- * `CLAUDE_CODE_OAUTH_TOKEN`). Bedrock authenticates from the AWS_ env vars via
- * pi-ai, so it needs no anthropic token.
+ * 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 resolveEffectiveProvider(): EffectiveProvider {
-  // Bedrock — env flag.
-  if (process.env.CLAUDE_CODE_USE_BEDROCK === '1') {
-    return { providerId: 'amazon-bedrock' };
+export function resolveProviderCredentials(providerId: string): ProviderCredentials {
+  const credentials: ProviderCredentials = {};
+
+  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;
+    }
   }
-
-  // Custom base URL — env contract.
-  if (process.env.ANTHROPIC_BASE_URL && process.env.ANTHROPIC_AUTH_TOKEN) {
-    return {
-      providerId: 'anthropic',
-      baseUrl: process.env.ANTHROPIC_BASE_URL,
-      anthropicToken: process.env.ANTHROPIC_AUTH_TOKEN,
-    };
+  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;
 
-  // Direct Anthropic (API key, or OAuth token).
-  const eff: EffectiveProvider = { providerId: 'anthropic' };
-  const token = process.env.ANTHROPIC_API_KEY ?? process.env.CLAUDE_CODE_OAUTH_TOKEN;
-  if (token) eff.anthropicToken = token;
-  return eff;
-}
-
-/** Resolve a model tier to a concrete model ID (env override → default). */
-export function resolveModelId(tier: ModelTier = 'medium'): string {
-  switch (tier) {
-    case 'small':
-      return process.env.ANTHROPIC_SMALL_MODEL || DEFAULT_MODELS.small;
-    case 'large':
-      return process.env.ANTHROPIC_LARGE_MODEL || DEFAULT_MODELS.large;
-    default:
-      return process.env.ANTHROPIC_MEDIUM_MODEL || DEFAULT_MODELS.medium;
-  }
-}
-
-/** Whether a model supports adaptive thinking. Opus 4.6, 4.7, and 4.8 only. */
-export function supportsAdaptiveThinking(model: string): boolean {
-  return /opus-4-[678]/.test(model);
+  return credentials;
 }
 
 /**
- * Resolve the thinking level for a run.
+ * In-memory credential store holding the selected provider's API key.
  *
- * Adaptive thinking is enabled only on capable models (Opus 4.6/4.7/4.8), mapped to
- * pi's 'medium' level; every other model runs with thinking 'off'. The
- * CLAUDE_ADAPTIVE_THINKING=false kill switch forces 'off' regardless of model.
+ * pi ships the `CredentialStore` interface but no in-memory implementation — its
+ * own store reads `auth.json` from disk. Shannon's credentials arrive as env vars
+ * in an ephemeral container, so nothing may be read from or written to disk.
  */
-export function resolveThinkingLevel(modelId: string): ThinkingLevel {
-  if (process.env.CLAUDE_ADAPTIVE_THINKING === 'false') return 'off';
-  return supportsAdaptiveThinking(modelId) ? 'medium' : 'off';
+class RuntimeCredentialStore implements CredentialStore {
+  private readonly credentials = new Map<string, Credential>();
+
+  constructor(providerId: string, apiKey: string | undefined) {
+    if (apiKey) {
+      this.credentials.set(providerId, { type: 'api_key', key: apiKey });
+    }
+  }
+
+  async read(providerId: string): Promise<Credential | undefined> {
+    return this.credentials.get(providerId);
+  }
+
+  async list(): Promise<readonly CredentialInfo[]> {
+    return [...this.credentials].map(([providerId, credential]) => ({ providerId, type: credential.type }));
+  }
+
+  /** Serialized read-modify-write. `fn` returning undefined leaves the entry alone. */
+  async modify(
+    providerId: string,
+    fn: (current: Credential | undefined) => Promise<Credential | undefined>,
+  ): Promise<Credential | undefined> {
+    const next = await fn(this.credentials.get(providerId));
+    if (next !== undefined) {
+      this.credentials.set(providerId, next);
+    }
+    return this.credentials.get(providerId);
+  }
+
+  async delete(providerId: string): Promise<void> {
+    this.credentials.delete(providerId);
+  }
+}
+
+/** 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) });
 }
 
 export interface ModelSelection {
   model: Model<Api>;
-  thinkingLevel: ThinkingLevel;
-  authStorage: AuthStorage;
+  modelRuntime: ModelRuntime;
   modelId: string;
   providerId: string;
 }
 
 /**
- * Resolve the active provider (see resolveEffectiveProvider), prime an AuthStorage
- * with its credential, and resolve the tier's model from a fresh ModelRegistry.
- * Anthropic / custom-base-URL use a runtime anthropic key; Bedrock authenticates
- * from the AWS_ env vars (bearer token primed explicitly as a belt-and-suspenders).
+ * Point a model descriptor at a gateway.
+ *
+ * An OpenAI gateway may serve either wire format, named by
+ * SHANNON_AI_OPENAI_FORMAT and defaulting to chat completions, which is what
+ * most gateway software exposes. Switching to completions also drops the stored
+ * `compat` block: the catalogue's block describes Responses, and an explicit
+ * entry outranks pi's `detectCompat`, so leaving it would apply Responses
+ * settings to a completions request. Staying on Responses keeps it, since it
+ * then describes the format in use. Every other provider has one API and only
+ * changes address.
  */
-export function resolveModelSelection(
-  registryFactory: (authStorage: AuthStorage) => ModelRegistry,
-  modelTier: ModelTier,
-): ModelSelection {
-  const eff = resolveEffectiveProvider();
-  const modelId = resolveModelId(modelTier);
+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 };
 
-  const authStorage = AuthStorage.inMemory();
-  if (eff.providerId === 'anthropic' && eff.anthropicToken) {
-    authStorage.setRuntimeApiKey('anthropic', eff.anthropicToken);
-  }
-  // Bedrock auth flows from the AWS_ env vars; prime the bearer token explicitly so
-  // it resolves via AuthStorage in addition to pi-ai's own env fallback.
-  if (eff.providerId === 'amazon-bedrock' && process.env.AWS_BEARER_TOKEN_BEDROCK) {
-    authStorage.setRuntimeApiKey('amazon-bedrock', process.env.AWS_BEARER_TOKEN_BEDROCK);
-  }
-
-  const registry = registryFactory(authStorage);
-  const found = registry.find(eff.providerId, modelId);
-  if (!found) {
-    throw new Error(`Model not found in pi registry: provider="${eff.providerId}" model="${modelId}"`);
-  }
-
-  // Custom base URL: override the resolved model's endpoint.
-  const model: Model<Api> = eff.baseUrl ? { ...found, baseUrl: eff.baseUrl } : found;
-
-  return {
-    model,
-    thinkingLevel: resolveThinkingLevel(modelId),
-    authStorage,
-    modelId,
-    providerId: eff.providerId,
-  };
+  const { compat: _responsesCompat, ...withoutCompat } = model;
+  return { ...withoutCompat, baseUrl, api: OPENAI_FORMATS['chat-completions'] };
 }
 
 /**
- * Whether a model is in the Fable family. Fable's safety classifiers flag
- * cybersecurity tasks and route them to Opus 4.8, so a security scan on Fable
- * largely runs on Opus 4.8 anyway.
+ * Resolve a model against a runtime.
+ *
+ * Direct to a provider, the model must exist in the catalogue. Behind a custom
+ * endpoint it need not: a gateway may serve models under its own names, so an
+ * unknown id is passed through on a descriptor borrowed from the provider's
+ * catalogue for its API dialect. Cost and context window on such a descriptor
+ * are the reference model's, so spend figures are approximate there.
+ *
+ * Returns undefined when the id is unresolvable — unknown with no endpoint
+ * override, or a provider carrying no models at all.
  */
-export function isFableModel(model: string): boolean {
-  return /fable/i.test(model);
+export function resolveModel(
+  modelRuntime: ModelRuntime,
+  providerId: string,
+  modelId: string,
+  baseUrl: string | undefined,
+  format: OpenAiFormat = DEFAULT_OPENAI_FORMAT,
+): Model<Api> | undefined {
+  const found = modelRuntime.getModel(providerId, modelId);
+  if (found) {
+    return baseUrl ? pointAtGateway(found, providerId, baseUrl, format) : found;
+  }
+  if (!baseUrl) return undefined;
+
+  const reference = modelRuntime.getModels(providerId)[0];
+  if (!reference) return undefined;
+
+  return pointAtGateway({ ...reference, id: modelId, name: modelId }, providerId, baseUrl, format);
+}
+
+/**
+ * Validate SHANNON_AI_OPENAI_FORMAT against the rest of the configuration and
+ * return the format a gateway run should use.
+ *
+ * The variable only reaches a request when both an OpenAI model and a gateway
+ * are configured, so it is rejected outside that combination rather than
+ * silently ignored.
+ */
+export function resolveGatewayFormat(providerId: string, baseUrl: string | undefined): OpenAiFormat {
+  const configured = resolveOpenAiFormat();
+  if (!configured) return DEFAULT_OPENAI_FORMAT;
+
+  if (providerId !== 'openai') {
+    throw new Error(
+      `SHANNON_AI_OPENAI_FORMAT applies to openai models only, but SHANNON_AI_MODEL selects "${providerId}". ` +
+        `${providerId} serves a single API, so there is no format to choose.`,
+    );
+  }
+  if (!baseUrl) {
+    throw new Error(
+      'SHANNON_AI_OPENAI_FORMAT applies to gateway runs only. Set SHANNON_AI_BASE_URL, or unset the format to call OpenAI directly.',
+    );
+  }
+  return configured;
+}
+
+/**
+ * Resolve SHANNON_AI_MODEL, build a ModelRuntime primed with the provider's
+ * credential, and look the model up in it.
+ */
+export async function resolveModelSelection(): Promise<ModelSelection> {
+  const { providerId, modelId } = resolveModelSpec();
+  const credentials = resolveProviderCredentials(providerId);
+  const format = resolveGatewayFormat(providerId, credentials.baseUrl);
+
+  const modelRuntime = await createModelRuntime(providerId, credentials.apiKey);
+
+  const model = resolveModel(modelRuntime, providerId, modelId, credentials.baseUrl, format);
+  if (!model) {
+    throw new Error(
+      `Model not found in pi registry: provider="${providerId}" model="${modelId}". Browse valid providers and models at ${PI_CATALOG_URL}.`,
+    );
+  }
+
+  return {
+    model,
+    modelRuntime,
+    modelId,
+    providerId,
+  };
 }

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

@@ -9,11 +9,11 @@
 import os from 'node:os';
 import type { AgentMessage } from '@earendil-works/pi-agent-core';
 import {
+  type AgentSession,
   type AgentSessionEvent,
   createAgentSession,
   DefaultResourceLoader,
   getAgentDir,
-  ModelRegistry,
   type ResourceLoader,
   SessionManager,
   SettingsManager,
@@ -23,16 +23,14 @@ import {
 import { fs, path } from 'zx';
 import type { AuditSession } from '../../audit/index.js';
 import { BASH_TIMEOUT_EXTENSION_DIR, deliverablesDir } from '../../paths.js';
-import { isRetryableError, PentestError } from '../../services/error-handling.js';
+import { isRetryableFailure, PentestError } from '../../services/error-handling.js';
 import { AGENT_VALIDATORS } from '../../session-manager.js';
 import type { ActivityLogger } from '../../types/activity-logger.js';
-import { ErrorCode } from '../../types/errors.js';
-import { isSpendingCapBehavior, matchesBillingTextPattern } from '../../utils/billing-detection.js';
 import { isBrowserAgent } from '../../utils/browser-agents.js';
 import { formatTimestamp } from '../../utils/formatting.js';
 import { Timer } from '../../utils/metrics.js';
 import { createAuditLogger } from '../audit-logger.js';
-import { type ModelTier, resolveModelSelection } from '../models.js';
+import { resolveModelSelection } from '../models.js';
 import {
   detectExecutionContext,
   formatAssistantOutput,
@@ -43,8 +41,10 @@ import {
 import { createProgressManager } from '../progress-manager.js';
 import type { CapturedSubmitTool } from '../submit-tool.js';
 import { permissionSystemConfigExists, permissionSystemPackageDir } from './permission-system.js';
+import { PI_RETRY_SETTINGS } from './retry-settings.js';
 import { createGlobTool, createTodoWriteTool } from './session-tools.js';
 import { createTaskTool } from './task-tool.js';
+import { providerTurnError } from './turn-error.js';
 
 declare global {
   var SHANNON_DISABLE_LOADER: boolean | undefined;
@@ -105,15 +105,41 @@ async function buildResourceLoader(
   return loader;
 }
 
+interface ChildUsage {
+  cost: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+/**
+ * Usage for one agent: the parent session plus every `task` sub-session it
+ * spawned. Sub-sessions keep their own stats, so their spend is accumulated
+ * separately and added here.
+ */
+function totalUsage(session: AgentSession | undefined, childUsage: ChildUsage) {
+  const stats = session?.getSessionStats();
+  return {
+    cost: (stats?.cost ?? 0) + childUsage.cost,
+    inputTokens: (stats?.tokens.input ?? 0) + childUsage.inputTokens,
+    outputTokens: (stats?.tokens.output ?? 0) + childUsage.outputTokens,
+    cacheReadTokens: (stats?.tokens.cacheRead ?? 0) + childUsage.cacheReadTokens,
+    cacheWriteTokens: (stats?.tokens.cacheWrite ?? 0) + childUsage.cacheWriteTokens,
+  };
+}
+
 export interface PiPromptResult {
   result?: string | null | undefined;
   success: boolean;
   duration: number;
   turns?: number | undefined;
   cost: number;
+  inputTokens?: number | undefined;
+  outputTokens?: number | undefined;
+  cacheReadTokens?: number | undefined;
+  cacheWriteTokens?: number | undefined;
   model?: string | undefined;
-  partialCost?: number | undefined;
-  apiErrorDetected?: boolean | undefined;
   error?: string | undefined;
   errorType?: string | undefined;
   prompt?: string | undefined;
@@ -138,7 +164,7 @@ async function writeErrorLog(
       timestamp: formatTimestamp(),
       agent: 'pi-executor',
       error: { name: err.constructor.name, message: err.message, code: err.code, status: err.status, stack: err.stack },
-      context: { sourceDir, prompt: `${fullPrompt.slice(0, 200)}...`, retryable: isRetryableError(err) },
+      context: { sourceDir, prompt: `${fullPrompt.slice(0, 200)}...`, retryable: isRetryableFailure(err) },
       duration,
     };
     const logPath = path.join(deliverablesDir(sourceDir), 'error.log');
@@ -190,28 +216,6 @@ function extractAssistantText(message: AgentMessage): string {
     .join('\n');
 }
 
-/**
- * Classify error-bearing text into a PentestError, mirroring the prior provider error
- * handling. Spending-cap / billing text is retryable (Temporal backs off and
- * recovers when the cap resets); session limit is permanent.
- */
-function classifyErrorText(content: string): PentestError | null {
-  if (!content) return null;
-  if (matchesBillingTextPattern(content)) {
-    return new PentestError(
-      `Billing limit reached: ${content.slice(0, 100)}`,
-      'billing',
-      true,
-      {},
-      ErrorCode.SPENDING_CAP_REACHED,
-    );
-  }
-  if (content.toLowerCase().includes('session limit reached')) {
-    return new PentestError('Session limit reached', 'billing', false);
-  }
-  return null;
-}
-
 // Low-level pi execution. Drives one agent session to completion with progress and
 // audit logging. Exported for Temporal activities to call single-attempt execution.
 export async function runPiPrompt(
@@ -222,7 +226,6 @@ export async function runPiPrompt(
   agentName: string | null = null,
   auditSession: AuditSession | null = null,
   logger: ActivityLogger,
-  modelTier: ModelTier = 'medium',
   callerTools?: ToolDefinition[],
   deliverablesSubdir?: string,
   cancellationSignal?: AbortSignal,
@@ -254,21 +257,22 @@ export async function runPiPrompt(
 
   // 4. Resolve model + auth, then assemble the tool set (universal task/todo tools
   //    plus any caller-supplied collector/submit tools).
-  const selection = resolveModelSelection((auth) => ModelRegistry.create(auth), modelTier);
+  const selection = await resolveModelSelection();
   const resourceLoader = await buildResourceLoader(sourceDir, logger, agentName);
   // Accumulates usage from in-process `task` child sessions so the parent's reported
   // cost includes sub-agent spend (their getSessionStats is separate from ours).
-  const childUsage = { cost: 0, inputTokens: 0, outputTokens: 0 };
+  const childUsage: ChildUsage = { cost: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
   const customTools: ToolDefinition[] = [
     createTaskTool({
       model: selection.model,
-      thinkingLevel: selection.thinkingLevel,
-      authStorage: selection.authStorage,
+      modelRuntime: selection.modelRuntime,
       cwd: sourceDir,
       onUsage: (usage) => {
         childUsage.cost += usage.cost;
         childUsage.inputTokens += usage.inputTokens;
         childUsage.outputTokens += usage.outputTokens;
+        childUsage.cacheReadTokens += usage.cacheReadTokens;
+        childUsage.cacheWriteTokens += usage.cacheWriteTokens;
       },
       resourceLoader,
       ...(cancellationSignal && { cancellationSignal }),
@@ -283,24 +287,40 @@ export async function runPiPrompt(
 
   let turnCount = 0;
   let pendingError: PentestError | null = null;
-  let apiErrorDetected = false;
+  // 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 {
-    const { session } = await createAgentSession({
+    ({ session } = await createAgentSession({
       cwd: sourceDir,
       model: selection.model,
-      thinkingLevel: selection.thinkingLevel,
       tools,
       customTools,
-      authStorage: selection.authStorage,
+      modelRuntime: selection.modelRuntime,
       sessionManager: SessionManager.inMemory(),
-      // Temporal owns retry; pi compaction stays on (no analog previously, guards
-      // against context overflow on long agent runs).
-      settingsManager: SettingsManager.inMemory({ retry: { enabled: false }, compaction: { enabled: true } }),
+      // Temporal owns agent restarts, pi absorbs transport faults (see
+      // PI_RETRY_SETTINGS); compaction stays on to guard against context overflow
+      // on long agent runs.
+      settingsManager: SettingsManager.inMemory({ retry: PI_RETRY_SETTINGS, compaction: { enabled: true } }),
       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) => {
@@ -314,15 +334,9 @@ export async function runPiPrompt(
             progress.stop();
             outputLines(formatAssistantOutput(text, execContext, turnCount, description));
             progress.start();
-            const billing = classifyErrorText(text);
-            if (billing) pendingError = billing;
           }
           if (msg.role === 'assistant' && msg.stopReason === 'error') {
-            apiErrorDetected = true;
-            pendingError =
-              pendingError ??
-              classifyErrorText(msg.errorMessage ?? '') ??
-              new PentestError(`Agent error: ${(msg.errorMessage ?? 'unknown').slice(0, 200)}`, 'unknown', true);
+            pendingError = pendingError ?? providerTurnError(msg, 'Agent error', selection.model.contextWindow);
           }
           break;
         }
@@ -348,7 +362,6 @@ export async function runPiPrompt(
           if (!event.aborted && !event.willRetry && event.errorMessage) {
             pendingError =
               pendingError ??
-              classifyErrorText(event.errorMessage) ??
               new PentestError(`Context compaction failed: ${event.errorMessage.slice(0, 200)}`, 'unknown', true);
           }
           break;
@@ -365,19 +378,9 @@ export async function runPiPrompt(
     if (pendingError) throw pendingError;
 
     // 8. Read usage/cost and final text.
-    const stats = session.getSessionStats();
-    const totalCost = stats.cost + childUsage.cost;
+    const usage = totalUsage(session, childUsage);
     const result = session.getLastAssistantText() ?? null;
 
-    // 9. Defense-in-depth: detect a spending cap that produced an empty/cheap run.
-    if (isSpendingCapBehavior(turnCount, totalCost, result || '')) {
-      throw new PentestError(
-        `Spending cap likely reached (turns=${turnCount}, cost=$0): ${result?.slice(0, 100)}`,
-        'billing',
-        true,
-      );
-    }
-
     const duration = timer.stop();
     progress.finish(formatCompletionMessage(execContext, description, turnCount, duration));
 
@@ -390,10 +393,12 @@ export async function runPiPrompt(
       success: true,
       duration,
       turns: turnCount,
-      cost: totalCost,
+      cost: usage.cost,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheWriteTokens: usage.cacheWriteTokens,
       model: selection.model.id,
-      partialCost: totalCost,
-      apiErrorDetected,
       ...(structuredOutput !== undefined && { structuredOutput }),
     };
   } catch (error) {
@@ -402,17 +407,29 @@ export async function runPiPrompt(
     const err = error as Error & { code?: string; status?: number };
     await auditLogger.logError(err, duration, turnCount);
     progress.stop();
-    outputLines(formatErrorOutput(err, execContext, description, duration, sourceDir, isRetryableError(err)));
+    outputLines(formatErrorOutput(err, execContext, description, duration, sourceDir, isRetryableFailure(err)));
     await writeErrorLog(err, sourceDir, fullPrompt, duration);
 
+    // A failed agent still spent money — on its own turns and, since Shannon's
+    // prompts delegate the heavy work, mostly on `task` sub-agents. Both count
+    // toward the run's usage.
+    const usage = totalUsage(session, childUsage);
+
     return {
       error: err.message,
-      errorType: err.constructor.name,
+      errorType: err instanceof PentestError && err.code ? err.code : err.constructor.name,
       prompt: `${fullPrompt.slice(0, 100)}...`,
       success: false,
       duration,
-      cost: 0,
-      retryable: isRetryableError(err),
+      turns: turnCount,
+      cost: usage.cost,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheWriteTokens: usage.cacheWriteTokens,
+      retryable: isRetryableFailure(err),
     };
+  } finally {
+    cancellationSignal?.removeEventListener('abort', onCancellation);
   }
 }

apps/worker/src/ai/pi/retry-settings.ts

@@ -0,0 +1,28 @@
+// 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.
+
+/**
+ * Retry split between the two layers that can restart work.
+ *
+ * `enabled: false` turns off pi's own agent-level retry loop — Temporal owns
+ * agent restarts, and both retrying the same turn would compound. `provider`
+ * settings are read independently of that flag, so transport faults
+ * (408/409/429/5xx) are still absorbed inside the session, which is far cheaper
+ * than a Temporal retry that re-runs the agent and respends its tokens.
+ *
+ * `maxRetries` is handed to the selected vendor's SDK, which owns the backoff, so
+ * the schedule varies by provider rather than following one formula.
+ *
+ * NOTE: pi recommends keeping this at 0, since SDK-level retries consume
+ * out-of-usage-limit responses before pi's classifier can mark them terminal.
+ * Shannon accepts that trade for the transport-fault coverage. `maxRetryDelayMs`
+ * is left at pi's 60s default so a server asking for a longer wait fails fast
+ * instead of parking the activity.
+ */
+export const PI_RETRY_SETTINGS = {
+  enabled: false,
+  provider: { maxRetries: 8 },
+} as const;

apps/worker/src/ai/pi/task-tool.ts

@@ -16,28 +16,25 @@
  * resource loader, and a fixed child tool surface.
  */
 
-import type { ThinkingLevel } from '@earendil-works/pi-agent-core';
 import { type AssistantMessage, type Model, Type } from '@earendil-works/pi-ai';
 import {
-  type AuthStorage,
   createAgentSession,
   defineTool,
   getAgentDir,
-  type ModelRegistry,
+  type ModelRuntime,
   type ResourceLoader,
   SessionManager,
   SettingsManager,
   type ToolDefinition,
 } from '@earendil-works/pi-coding-agent';
+import { PI_RETRY_SETTINGS } from './retry-settings.js';
 
 export interface TaskToolContext {
   cwd: string;
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
   model: Model<any>;
-  thinkingLevel?: ThinkingLevel;
-  authStorage: AuthStorage;
-  /** Explicit model registry for sub-session resolution. Omit to inherit the parent's default. */
-  modelRegistry?: ModelRegistry;
+  /** Parent's model/auth runtime, reused so sub-agents share its resolved credential. */
+  modelRuntime: ModelRuntime;
   resourceLoader: ResourceLoader;
   cancellationSignal?: AbortSignal | undefined;
   /**
@@ -46,7 +43,13 @@ export interface TaskToolContext {
    * so without this their spend (the bulk of a whitebox run, since Shannon
    * prompts delegate the heavy work) is invisible to billing.
    */
-  onUsage?: (usage: { cost: number; inputTokens: number; outputTokens: number }) => void;
+  onUsage?: (usage: {
+    cost: number;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+  }) => void;
 }
 
 const CHILD_TOOLS = ['read', 'grep', 'find', 'ls', 'write', 'bash'];
@@ -83,13 +86,11 @@ export function createTaskTool(config: TaskToolContext): ToolDefinition {
         agentDir,
         resourceLoader: config.resourceLoader,
         model: config.model,
-        ...(config.thinkingLevel && { thinkingLevel: config.thinkingLevel }),
         tools: CHILD_TOOLS,
-        authStorage: config.authStorage,
-        ...(config.modelRegistry && { modelRegistry: config.modelRegistry }),
+        modelRuntime: config.modelRuntime,
         sessionManager: SessionManager.inMemory(config.cwd),
         settingsManager: SettingsManager.inMemory({
-          retry: { enabled: false },
+          retry: PI_RETRY_SETTINGS,
           compaction: { enabled: true },
         }),
       });
@@ -109,8 +110,6 @@ export function createTaskTool(config: TaskToolContext): ToolDefinition {
 
       let resultText = '';
       let subCost = 0;
-      let subInputTokens = 0;
-      let subOutputTokens = 0;
       subSession.subscribe((event) => {
         if (event.type === 'turn_end') {
           const msg = event.message as AssistantMessage | undefined;
@@ -120,8 +119,6 @@ export function createTaskTool(config: TaskToolContext): ToolDefinition {
             }
           }
           if (msg?.usage?.cost?.total != null) subCost += msg.usage.cost.total;
-          subInputTokens += msg?.usage?.input ?? 0;
-          subOutputTokens += msg?.usage?.output ?? 0;
         }
       });
 
@@ -138,7 +135,13 @@ export function createTaskTool(config: TaskToolContext): ToolDefinition {
         // Read stats before dispose; reconcile cost the same way the parent does.
         const subStats = subSession.getSessionStats();
         if (subStats.cost > subCost) subCost = subStats.cost;
-        config.onUsage?.({ cost: subCost, inputTokens: subInputTokens, outputTokens: subOutputTokens });
+        config.onUsage?.({
+          cost: subCost,
+          inputTokens: subStats.tokens.input,
+          outputTokens: subStats.tokens.output,
+          cacheReadTokens: subStats.tokens.cacheRead,
+          cacheWriteTokens: subStats.tokens.cacheWrite,
+        });
       } finally {
         config.cancellationSignal?.removeEventListener('abort', onCancellation);
         subSession.dispose();

apps/worker/src/ai/pi/turn-error.ts

@@ -0,0 +1,44 @@
+// 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.
+
+import { type AssistantMessage, isContextOverflow, isRetryableAssistantError } from '@earendil-works/pi-ai';
+import { PentestError } from '../../services/error-handling.js';
+import { ErrorCode } from '../../types/errors.js';
+
+/**
+ * Wrap a failed assistant turn, taking the verdict from pi.
+ *
+ * Overflow is separated first, as pi's retry contract requires: it means the
+ * request was too large, not that the provider faltered, so an identical retry
+ * would overflow again. Everything else goes to pi's classifier, which treats
+ * quota, billing, and auth exhaustion as terminal and load, throttling, and
+ * transport faults as transient — those were already retried in-session, so
+ * reaching here means the attempts were exhausted.
+ *
+ * `contextWindow` is omitted where overflow cannot apply, such as a one-word
+ * credential probe.
+ */
+export function providerTurnError(message: AssistantMessage, label: string, contextWindow?: number): PentestError {
+  const detail = (message.errorMessage ?? 'unknown provider error').slice(0, 300);
+
+  if (contextWindow !== undefined && isContextOverflow(message, contextWindow)) {
+    return new PentestError(
+      `${label}: context window exceeded after compaction: ${detail}`,
+      'unknown',
+      false,
+      { contextWindow },
+      ErrorCode.AGENT_EXECUTION_FAILED,
+    );
+  }
+
+  return new PentestError(
+    `${label}: ${detail}`,
+    'unknown',
+    isRetryableAssistantError(message),
+    {},
+    ErrorCode.AGENT_EXECUTION_FAILED,
+  );
+}

apps/worker/src/ai/queue-schemas.ts

@@ -14,6 +14,7 @@
 
 import { defineTool } from '@earendil-works/pi-coding-agent';
 import { type Static, type TObject, Type } from 'typebox';
+import { stringEnum } from '../collectors/schema.js';
 import type { AgentName } from '../types/agents.js';
 import type { CapturedSubmitTool } from './submit-tool.js';
 
@@ -23,13 +24,38 @@ function optStr(description?: string) {
   return Type.Optional(Type.String(description === undefined ? {} : { description }));
 }
 
-/** Base fields shared by every queue entry. `notes` gains guidance in analysis mode. */
+/**
+ * Base fields shared by every queue entry. `notes` gains guidance in analysis mode.
+ *
+ * `confidence` is enumerated so it reaches the report agent in the same casing the report
+ * schema accepts — an analysis-only run carries it through verbatim as its only rating.
+ */
 function baseFields(exploit: boolean) {
   return {
     ID: Type.String(),
     vulnerability_type: Type.String(),
     externally_exploitable: Type.Boolean(),
-    confidence: Type.String(),
+    confidence: stringEnum(['high', 'medium', 'low'], {
+      description: 'Confidence that this is a real, reachable vulnerability.',
+    }),
+    code_locations: Type.Optional(
+      Type.Array(
+        Type.Object({
+          file: Type.String({ description: 'Repository-relative path, no leading slash.' }),
+          start_line: Type.Optional(Type.Integer({ minimum: 1 })),
+          end_line: Type.Optional(Type.Integer({ minimum: 1, description: 'Set when the flaw spans a range.' })),
+          role: stringEnum(['sink', 'source', 'guard'], {
+            description:
+              'sink where the flaw manifests, source where untrusted input enters, guard for a check ' +
+              'that is missing or misplaced.',
+          }),
+          symbol: Type.Optional(
+            Type.String({ description: 'Enclosing function or method, named as written in the code.' }),
+          ),
+        }),
+        { description: 'Every code site this finding touches, sink first.' },
+      ),
+    ),
     notes: exploit ? optStr() : optStr(ANALYSIS_NOTES_DESCRIPTION),
   };
 }
@@ -94,6 +120,8 @@ const authEntry = () => Type.Object({ ...baseFields(true), ...authFields });
 const ssrfEntry = () => Type.Object({ ...baseFields(true), ...ssrfFields });
 const authzEntry = () => Type.Object({ ...baseFields(true), ...authzFields });
 
+export type QueueCodeLocation = NonNullable<Static<ReturnType<typeof injectionEntry>>['code_locations']>[number];
+
 export type InjectionFinding = Static<ReturnType<typeof injectionEntry>>;
 export type XssFinding = Static<ReturnType<typeof xssEntry>>;
 export type AuthFinding = Static<ReturnType<typeof authEntry>>;

apps/worker/src/audit/metrics-tracker.ts

@@ -23,6 +23,11 @@ interface AttemptData {
   attempt_number: number;
   duration_ms: number;
   cost_usd: number;
+  input_tokens?: number | undefined;
+  output_tokens?: number | undefined;
+  cache_read_tokens?: number | undefined;
+  cache_write_tokens?: number | undefined;
+  turns?: number | undefined;
   success: boolean;
   timestamp: string;
   model?: string | undefined;
@@ -34,6 +39,10 @@ interface AgentAuditMetrics {
   attempts: AttemptData[];
   final_duration_ms: number;
   total_cost_usd: number;
+  total_input_tokens: number;
+  total_output_tokens: number;
+  total_cache_read_tokens: number;
+  total_cache_write_tokens: number;
   model?: string | undefined;
   checkpoint?: string | undefined;
 }
@@ -174,6 +183,10 @@ export class MetricsTracker {
       attempts: [],
       final_duration_ms: 0,
       total_cost_usd: 0,
+      total_input_tokens: 0,
+      total_output_tokens: 0,
+      total_cache_read_tokens: 0,
+      total_cache_write_tokens: 0,
     };
     this.data.metrics.agents[agentName] = agent;
 
@@ -184,6 +197,11 @@ export class MetricsTracker {
       cost_usd: result.cost_usd,
       success: result.success,
       timestamp: formatTimestamp(),
+      ...(result.input_tokens !== undefined && { input_tokens: result.input_tokens }),
+      ...(result.output_tokens !== undefined && { output_tokens: result.output_tokens }),
+      ...(result.cache_read_tokens !== undefined && { cache_read_tokens: result.cache_read_tokens }),
+      ...(result.cache_write_tokens !== undefined && { cache_write_tokens: result.cache_write_tokens }),
+      ...(result.turns !== undefined && { turns: result.turns }),
     };
 
     if (result.model) {
@@ -197,8 +215,12 @@ export class MetricsTracker {
     // 3. Append attempt to history
     agent.attempts.push(attempt);
 
-    // 4. Recalculate total cost across all attempts (includes failures)
+    // 4. Recalculate totals across all attempts (includes failures)
     agent.total_cost_usd = agent.attempts.reduce((sum, a) => sum + a.cost_usd, 0);
+    agent.total_input_tokens = agent.attempts.reduce((sum, a) => sum + (a.input_tokens ?? 0), 0);
+    agent.total_output_tokens = agent.attempts.reduce((sum, a) => sum + (a.output_tokens ?? 0), 0);
+    agent.total_cache_read_tokens = agent.attempts.reduce((sum, a) => sum + (a.cache_read_tokens ?? 0), 0);
+    agent.total_cache_write_tokens = agent.attempts.reduce((sum, a) => sum + (a.cache_write_tokens ?? 0), 0);
 
     // 5. Update agent status based on outcome
     if (result.success) {

apps/worker/src/audit/workflow-logger.ts

@@ -12,7 +12,6 @@
  */
 
 import fs from 'node:fs/promises';
-import { isFableModel, resolveModelId } from '../ai/models.js';
 import { formatDuration, formatTimestamp } from '../utils/formatting.js';
 import { LogStream } from './log-stream.js';
 import { generateWorkflowLogPath, type SessionMetadata } from './utils.js';
@@ -87,19 +86,6 @@ export class WorkflowLogger {
       `Started:     ${formatTimestamp()}`,
     ];
 
-    // Surface Fable usage: its safety classifiers route cybersecurity tasks to
-    // Opus 4.8, so those phases run on Opus 4.8 regardless of the tier setting.
-    const fableTiers = (['small', 'medium', 'large'] as const)
-      .map((tier) => ({ tier, model: resolveModelId(tier) }))
-      .filter(({ model }) => isFableModel(model));
-    if (fableTiers.length > 0) {
-      const tierList = fableTiers.map(({ tier, model }) => `${tier} (${model})`).join(', ');
-      lines.push(
-        `Note:        ${tierList} set to a Fable model. Fable's safety classifiers`,
-        `             route cybersecurity tasks to Opus 4.8, so those phases run on Opus 4.8.`,
-      );
-    }
-
     lines.push(`================================================================================`, ``);
 
     return this.logStream.write(lines.join('\n'));
@@ -317,13 +303,17 @@ export class WorkflowLogger {
    * Output: "Error:       phase context\n             ErrorType\n             ..."
    */
   private formatErrorBlock(errorString: string): string {
-    const segments = errorString.split('|');
     const label = 'Error:       ';
     const indent = ' '.repeat(label.length);
 
-    const lines = segments.map((segment, i) => (i === 0 ? `${label}${segment.trim()}` : `${indent}${segment.trim()}`));
+    // Segments are delimited by '|'; a segment's own embedded newlines (e.g. a multi-line
+    // validation message) become their own lines so each aligns under the label.
+    const lines = errorString
+      .split(/[|\n]/)
+      .map((segment) => segment.trim())
+      .filter((segment) => segment.length > 0);
 
-    return `${lines.join('\n')}\n`;
+    return `${lines.map((line, i) => (i === 0 ? `${label}${line}` : `${indent}${line}`)).join('\n')}\n`;
   }
 
   /**
@@ -350,17 +340,19 @@ export class WorkflowLogger {
       lines.push(this.formatErrorBlock(summary.error).trimEnd());
     }
 
-    lines.push('');
-    lines.push('Agent Breakdown:');
+    if (summary.completedAgents.length > 0) {
+      lines.push('');
+      lines.push('Agent Breakdown:');
 
-    for (const agentName of summary.completedAgents) {
-      const metrics = summary.agentMetrics[agentName];
-      if (metrics) {
-        const duration = formatDuration(metrics.durationMs);
-        const cost = metrics.costUsd !== null ? `$${metrics.costUsd.toFixed(4)}` : 'N/A';
-        lines.push(`  - ${agentName} (${duration}, ${cost})`);
-      } else {
-        lines.push(`  - ${agentName}`);
+      for (const agentName of summary.completedAgents) {
+        const metrics = summary.agentMetrics[agentName];
+        if (metrics) {
+          const duration = formatDuration(metrics.durationMs);
+          const cost = metrics.costUsd !== null ? `$${metrics.costUsd.toFixed(4)}` : 'N/A';
+          lines.push(`  - ${agentName} (${duration}, ${cost})`);
+        } else {
+          lines.push(`  - ${agentName}`);
+        }
       }
     }
 

apps/worker/src/branding.ts

@@ -0,0 +1,18 @@
+// Copyright (C) 2025 Keygraph, Inc.
+
+/**
+ * Centralized brand strings for report deliverables.
+ *
+ * Kept in two parts because the two renderers join them differently: the Typst
+ * template splits its `brand` input on a pipe to set the cover's two lines
+ * (`report.typ:212`), while a human-read line takes an em dash.
+ */
+
+export const PRODUCT_NAME = 'Shannon';
+export const PRODUCT_DESCRIPTOR = 'AI Pentester by Keygraph';
+
+/** Cover wordmark for the Typst template, which parses the pipe. */
+export const TYPST_BRAND = `${PRODUCT_NAME} | ${PRODUCT_DESCRIPTOR}`;
+
+/** Attribution line for prose surfaces. */
+export const BRAND_LOCKUP = `${PRODUCT_NAME} — ${PRODUCT_DESCRIPTOR}`;

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

@@ -122,8 +122,7 @@ export function buildSchemas(validIds: ReadonlySet<string>) {
   const vulnerableLocationField = Type.String({
     minLength: 1,
     description:
-      'Endpoint or mechanism where the vulnerability exists (e.g. "GET /api/products?id=", ' +
-      '"POST /login", or a code location like "controllers/userController.js:42").',
+      'Endpoint or mechanism where the vulnerability exists (e.g. "GET /api/products?id=", ' + '"POST /login").',
   });
 
   const overviewField = Type.String({

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

@@ -0,0 +1,336 @@
+// 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.
+
+/**
+ * Finding Collector tools
+ *
+ * Collects structured findings from the report agent via a pi tool. The agent
+ * calls `add_finding` once per finding with TypeBox-validated parameters. After
+ * the agent finishes, the caller retrieves collected findings via `getAll()`
+ * for downstream rendering (markdown, PDF, DB).
+ *
+ * The tool schema is mode-dependent: fields describing a demonstrated attack have no source in
+ * an analysis-only run, and offering them would only make the agent invent them.
+ */
+
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { cleanInput, stringEnum } from './schema.js';
+
+// ============================================================================
+// SCHEMA
+// ============================================================================
+
+const OWASP_CATEGORY_VALUES = [
+  'A01:2025 — Broken Access Control',
+  'A02:2025 — Security Misconfiguration',
+  'A03:2025 — Software Supply Chain Failures',
+  'A04:2025 — Cryptographic Failures',
+  'A05:2025 — Injection',
+  'A06:2025 — Insecure Design',
+  'A07:2025 — Authentication Failures',
+  'A08:2025 — Software or Data Integrity Failures',
+  'A09:2025 — Security Logging and Alerting Failures',
+  'A10:2025 — Mishandling of Exceptional Conditions',
+] 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;
+
+const StepItemSchema = Type.Union([
+  Type.Object({
+    kind: Type.Literal('prose'),
+    text: Type.String({ minLength: 1, description: 'Narrative prose for this item.' }),
+  }),
+  Type.Object({
+    kind: Type.Literal('code'),
+    block: Type.Object({
+      language: Type.String({
+        description: 'Language identifier for syntax highlighting (e.g., "bash", "http", "json").',
+      }),
+      content: Type.String({ minLength: 1, description: 'The code content.' }),
+    }),
+  }),
+]);
+
+const StructuredStepSchema = Type.Object({
+  title: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description: 'Optional title for this step (e.g., "Send malicious payload").',
+    }),
+  ),
+  items: Type.Array(StepItemSchema, {
+    minItems: 1,
+    description: 'Ordered list of prose and code items that make up this step.',
+  }),
+});
+
+const CodeLocationSchema = Type.Object({
+  file: Type.String({
+    minLength: 1,
+    description: 'Repository-relative path, no leading slash (e.g., "routes/search.ts").',
+  }),
+  start_line: Type.Optional(
+    Type.Union([Type.Integer({ minimum: 1 }), Type.Null()], {
+      description: '1-indexed line number. Omit when the deliverable gives only a file.',
+    }),
+  ),
+  end_line: Type.Optional(
+    Type.Union([Type.Integer({ minimum: 1 }), Type.Null()], {
+      description: 'End of the range, when the finding spans multiple lines.',
+    }),
+  ),
+  role: stringEnum(['sink', 'source', 'guard'], {
+    description:
+      'What this location is in the data flow. `sink` is where the vulnerability manifests, `source` ' +
+      'where untrusted input enters, `guard` a check that is missing or misplaced.',
+  }),
+  symbol: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description: 'Enclosing function or method name, when known.',
+    }),
+  ),
+});
+
+const HttpLocationSchema = Type.Object({
+  method: Type.String({ minLength: 1, description: 'HTTP method (e.g., "GET", "POST").' }),
+  url: Type.String({ minLength: 1, description: 'Full URL of the affected endpoint.' }),
+  parameter: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description: 'The specific parameter carrying the payload, when the finding names one.',
+    }),
+  ),
+});
+
+const AdditionalSectionSchema = Type.Object({
+  heading: Type.String({
+    minLength: 1,
+    description: 'Section heading (e.g., "Real-World Attack Scenario").',
+  }),
+  items: Type.Array(StepItemSchema, {
+    minItems: 1,
+    description: 'Ordered prose and code items for this section.',
+  }),
+});
+
+/**
+ * `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.',
+    }),
+    title: Type.String({
+      minLength: 1,
+      description:
+        'Descriptive name (e.g., "SQL Injection — User Search", "IDOR — Unauthorized Access to User Orders").',
+    }),
+    category: stringEnum(['Injection', 'XSS', 'Authentication', 'Authorization', 'SSRF'], {
+      description:
+        'From the finding_id prefix: INJ-VULN-xxx Injection, ' +
+        'XSS-VULN-xxx XSS, AUTH-VULN-xxx Authentication, AUTHZ-VULN-xxx Authorization, ' +
+        'SSRF-VULN-xxx SSRF.',
+    }),
+    owasp_category: stringEnum(OWASP_CATEGORY_VALUES, {
+      description: 'OWASP Top Ten 2025 category.',
+    }),
+  };
+}
+
+function locationFields() {
+  return {
+    vulnerable_location: Type.String({
+      minLength: 1,
+      description: 'Endpoint or code location where the vulnerability exists.',
+    }),
+    http_location: Type.Optional(
+      Type.Union([HttpLocationSchema, Type.Null()], {
+        description:
+          'The HTTP request the finding is reached through, when the deliverable names one. Omit for ' +
+          'findings with no network entry point.',
+      }),
+    ),
+  };
+}
+
+/** `impact` is described per mode: an analysis run demonstrated nothing, and implying otherwise invites fabrication. */
+function narrativeFields(exploit: boolean) {
+  const impactDescription = exploit
+    ? 'What the exploit demonstrably achieved.'
+    : 'What an attacker could achieve if this were exploited. State it as assessed, not demonstrated.';
+
+  return {
+    overview: Type.String({
+      minLength: 1,
+      description: 'What the vulnerability is and why it matters. 2-3 sentences of professional prose.',
+    }),
+    impact: Type.String({ minLength: 1, description: impactDescription }),
+    remediation: Type.String({
+      minLength: 1,
+      description: 'Specific, actionable fix guidance. Code-level or configuration-level.',
+    }),
+  };
+}
+
+/** Fields that only mean something once an exploit has run. Absent from the analysis schema. */
+function exploitOnlyFields() {
+  return {
+    auth_state: Type.String({
+      minLength: 1,
+      description: 'Authentication state during testing (e.g., "Unauthenticated", "Any authenticated user").',
+    }),
+    prerequisites: Type.String({
+      minLength: 1,
+      description: 'What is needed to exploit the vulnerability (or "None").',
+    }),
+    exploitation_steps: Type.Array(StructuredStepSchema, {
+      minItems: 1,
+      description: 'Ordered exploitation steps. Each step has an optional title and prose/code items.',
+    }),
+    proof_of_impact: Type.Array(StepItemSchema, {
+      minItems: 1,
+      description: 'Evidence of what the exploit achieved — prose and code items.',
+    }),
+    status: Type.Optional(
+      Type.Union([stringEnum(STATUS_VALUES), Type.Null()], {
+        description: 'Finding status. Use "exploited" for confirmed exploits.',
+      }),
+    ),
+  };
+}
+
+/** Accompanies `severity` when nothing was exploited — the rating the analysis deliverable itself carries. */
+function analysisOnlyFields() {
+  return {
+    confidence: stringEnum(CONFIDENCE_VALUES, {
+      description:
+        'Confidence that this is a real, reachable vulnerability. Carry it over from the analysis ' +
+        'deliverable rather than reassessing.',
+    }),
+  };
+}
+
+function sharedOptionalFields() {
+  return {
+    notes: Type.Optional(
+      Type.Union([Type.Array(StepItemSchema), Type.Null()], {
+        description: 'Additional context as prose/code items.',
+      }),
+    ),
+    additional_sections: Type.Optional(
+      Type.Union([Type.Array(AdditionalSectionSchema), Type.Null()], {
+        description: 'Extra report sections that do not fit into other fields (e.g., "Real-World Attack Scenario").',
+      }),
+    ),
+  };
+}
+
+export function buildAddFindingSchema(exploit: boolean) {
+  return Type.Object({
+    ...identityFields(exploit),
+    ...(exploit ? exploitOnlyFields() : analysisOnlyFields()),
+    ...locationFields(),
+    ...narrativeFields(exploit),
+    ...sharedOptionalFields(),
+  });
+}
+
+/**
+ * Superset of both modes, for typing only. Consumers must check presence rather than assume:
+ * `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(true),
+  code_locations: Type.Optional(Type.Array(CodeLocationSchema)),
+  auth_state: Type.Optional(Type.String()),
+  prerequisites: Type.Optional(Type.String()),
+  exploitation_steps: Type.Optional(Type.Array(StructuredStepSchema)),
+  proof_of_impact: Type.Optional(Type.Array(StepItemSchema)),
+  status: Type.Optional(Type.Union([stringEnum(STATUS_VALUES), Type.Null()])),
+  confidence: Type.Optional(Type.Union([stringEnum(CONFIDENCE_VALUES), Type.Null()])),
+  ...locationFields(),
+  ...narrativeFields(true),
+  ...sharedOptionalFields(),
+});
+
+export type AddFindingInput = Static<typeof AddFindingSupersetSchema>;
+
+// Re-export schema types for downstream consumers
+export type CodeLocation = Static<typeof CodeLocationSchema>;
+export type HttpLocation = Static<typeof HttpLocationSchema>;
+export type StepItem = Static<typeof StepItemSchema>;
+export type StructuredStep = Static<typeof StructuredStepSchema>;
+export type AdditionalSection = Static<typeof AdditionalSectionSchema>;
+
+// ============================================================================
+// RESPONSE HELPERS
+// ============================================================================
+
+function toolResult(payload: Record<string, unknown>) {
+  return {
+    content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+    details: undefined,
+  };
+}
+
+function successResult(data: Record<string, unknown>) {
+  return toolResult({ status: 'success', ...data });
+}
+
+function errorResult(message: string, errorType = 'ValidationError', retryable = true) {
+  return toolResult({ status: 'error', message, errorType, retryable });
+}
+
+// ============================================================================
+// COLLECTOR FACTORY
+// ============================================================================
+
+export interface FindingCollector {
+  tools: ToolDefinition[];
+  getAll(): AddFindingInput[];
+}
+
+export function createFindingCollector(exploit: boolean): FindingCollector {
+  const findings: AddFindingInput[] = [];
+  const schema = buildAddFindingSchema(exploit);
+
+  const addFindingTool = defineTool({
+    name: 'add_finding',
+    label: 'Add Finding',
+    description:
+      'Record a single finding as structured data for report rendering and DB persistence. Call once per finding after grouping/dedup. Duplicate finding_ids are rejected.',
+    parameters: schema,
+    async execute(_toolCallId, input) {
+      const existing = findings.find((f) => f.finding_id === input.finding_id);
+      if (existing) {
+        return errorResult(
+          `Finding ${input.finding_id} has already been recorded. Each finding may only be added once.`,
+          'DuplicateError',
+          false,
+        );
+      }
+      const typed = cleanInput(schema, input) as AddFindingInput;
+      findings.push(typed);
+      return successResult({ added: [typed.finding_id] });
+    },
+  });
+
+  return {
+    tools: [addFindingTool],
+    getAll: (): AddFindingInput[] => [...findings],
+  };
+}

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 => {
@@ -675,6 +679,8 @@ export const distributeConfig = (config: Config | null): DistributedConfig => {
   const exploit = config?.exploit !== undefined ? config.exploit === 'true' : true;
 
   const report = {
+    // Default on; only an explicit "false" opts out.
+    sarif: config?.report?.sarif !== 'false',
     ...(config?.report?.min_severity && { min_severity: config.report.min_severity }),
     ...(config?.report?.min_confidence && { min_confidence: config.report.min_confidence }),
     ...(config?.report?.guidance && { guidance: config.report.guidance.trim() }),
@@ -701,13 +707,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,20 @@ 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';
+
+/** SARIF 2.1.0 log, written for exploit=true runs unless report.sarif is set to false. */
+export const SARIF_FILENAME = 'report.sarif';
 
 /**
  * Resolve the session.json path for a run directory, preferring the current

apps/worker/src/scripts/set-report-meta.ts

@@ -0,0 +1,139 @@
+#!/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.
+
+/**
+ * set-report-meta CLI
+ *
+ * Writes top-level report metadata to report.json.
+ * Called once by the report agent before recording individual findings.
+ * Overwrites any existing report_meta — idempotent.
+ *
+ * Usage:
+ *   set-report-meta --target "https://example.com" --assessment-date "2026-05-07" \
+ *     --scope "injection, xss, auth, authz, ssrf" --executive-summary "..."
+ *
+ * Output (JSON to stdout):
+ *   { "status": "success" }
+ *   { "status": "error", "message": "...", "retryable": true }
+ */
+
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+const REPORT_FILENAME = 'report.json';
+
+interface ReportMeta {
+  target: string;
+  assessment_date: string;
+  scope: string;
+  executive_summary: string;
+}
+
+interface ReportFile {
+  report_meta?: ReportMeta;
+  findings: Array<Record<string, unknown>>;
+}
+
+const HELP = `set-report-meta — write top-level report metadata to report.json
+
+Usage:
+  set-report-meta --target "https://example.com" --assessment-date "2026-05-07" \\
+    --scope "injection, xss, auth" --executive-summary "..."
+
+Required flags: --target, --assessment-date, --scope, --executive-summary
+
+Output: JSON to stdout with status "success" or "error".`;
+
+function getFlag(argv: string[], flag: string): string | undefined {
+  for (let i = 2; i < argv.length; i++) {
+    if (argv[i] === flag && argv[i + 1] && !argv[i + 1]!.startsWith('--')) {
+      return argv[i + 1]!;
+    }
+  }
+  return undefined;
+}
+
+function readReportFile(filePath: string): ReportFile {
+  if (!existsSync(filePath)) {
+    return { findings: [] };
+  }
+  const raw = readFileSync(filePath, 'utf-8');
+  return JSON.parse(raw) as ReportFile;
+}
+
+function writeReportFile(filePath: string, data: ReportFile): void {
+  const tmpPath = `${filePath}.tmp`;
+  const payload = JSON.stringify(data, null, 2);
+  try {
+    writeFileSync(tmpPath, payload, 'utf-8');
+    renameSync(tmpPath, filePath);
+  } catch (err) {
+    try {
+      unlinkSync(tmpPath);
+    } catch {
+      /* best-effort */
+    }
+    throw err;
+  }
+}
+
+function main(): void {
+  if (process.argv[2] === '--help' || process.argv[2] === '-h') {
+    console.log(HELP);
+    return;
+  }
+
+  const target = getFlag(process.argv, '--target');
+  const assessmentDate = getFlag(process.argv, '--assessment-date');
+  const scope = getFlag(process.argv, '--scope');
+  const executiveSummary = getFlag(process.argv, '--executive-summary');
+
+  if (!target) {
+    console.log(JSON.stringify({ status: 'error', message: 'Missing required --target flag', retryable: true }));
+    process.exit(1);
+  }
+  if (!assessmentDate) {
+    console.log(
+      JSON.stringify({ status: 'error', message: 'Missing required --assessment-date flag', retryable: true }),
+    );
+    process.exit(1);
+  }
+  if (!scope) {
+    console.log(JSON.stringify({ status: 'error', message: 'Missing required --scope flag', retryable: true }));
+    process.exit(1);
+  }
+  if (!executiveSummary) {
+    console.log(
+      JSON.stringify({ status: 'error', message: 'Missing required --executive-summary flag', retryable: true }),
+    );
+    process.exit(1);
+  }
+
+  const subdir = process.env.SHANNON_DELIVERABLES_SUBDIR || '.shannon/deliverables';
+  const deliverablesDir = resolve(process.cwd(), ...subdir.split('/'));
+  mkdirSync(deliverablesDir, { recursive: true });
+  const filePath = resolve(deliverablesDir, REPORT_FILENAME);
+  const data = readReportFile(filePath);
+  data.report_meta = {
+    target,
+    assessment_date: assessmentDate,
+    scope,
+    executive_summary: executiveSummary,
+  };
+  writeReportFile(filePath, data);
+
+  console.log(JSON.stringify({ status: 'success' }));
+}
+
+try {
+  main();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.log(JSON.stringify({ status: 'error', message, retryable: true }));
+  process.exit(1);
+}

apps/worker/src/services/agent-execution.ts

@@ -13,7 +13,6 @@
  * - Create git checkpoint
  * - Start audit logging
  * - Invoke the pi agent via runPiPrompt
- * - Spending cap check using isSpendingCapBehavior
  * - Handle failure (rollback, audit)
  * - Validate output using AGENTS[agentName].deliverableFilename
  * - Render the deliverable to disk via the writeDeliverable hook (if provided)
@@ -34,7 +33,6 @@ import type { AgentEndResult } from '../types/audit.js';
 import { ErrorCode, type PentestErrorType } from '../types/errors.js';
 import type { AgentMetrics } from '../types/metrics.js';
 import { err, isErr, ok, type Result } from '../types/result.js';
-import { isSpendingCapBehavior } from '../utils/billing-detection.js';
 import { getAgentGitPaths } from './agent-git-paths.js';
 import type { ConfigLoaderService } from './config-loader.js';
 import { PentestError } from './error-handling.js';
@@ -55,6 +53,7 @@ export interface AgentExecutionInput {
   attemptNumber: number;
   promptDir?: string | undefined;
   customTools?: import('@earendil-works/pi-coding-agent').ToolDefinition[];
+  failedClasses?: readonly import('../types/config.js').VulnClass[] | undefined;
   // Renders the deliverable to disk; invoked after validation, before the success commit.
   writeDeliverable?: (deliverablesPath: string) => Promise<void>;
   cancellationSignal?: AbortSignal | undefined;
@@ -80,11 +79,6 @@ function errorCodeFromResult(result: PiPromptResult): ErrorCode {
 
 function categoryForErrorCode(code: ErrorCode): PentestErrorType {
   switch (code) {
-    case ErrorCode.SPENDING_CAP_REACHED:
-    case ErrorCode.INSUFFICIENT_CREDITS:
-    case ErrorCode.BILLING_ERROR:
-    case ErrorCode.API_RATE_LIMITED:
-      return 'billing';
     case ErrorCode.GIT_CHECKPOINT_FAILED:
     case ErrorCode.GIT_ROLLBACK_FAILED:
       return 'filesystem';
@@ -153,6 +147,7 @@ export class AgentExecutionService {
       attemptNumber,
       promptDir,
       customTools,
+      failedClasses,
       writeDeliverable,
       cancellationSignal,
     } = input;
@@ -171,7 +166,12 @@ export class AgentExecutionService {
     try {
       prompt = await loadPrompt(
         promptTemplate,
-        { webUrl, repoPath, AUTH_STATE_FILE: authStateFile(auditSession.sessionMetadata) },
+        {
+          webUrl,
+          repoPath,
+          AUTH_STATE_FILE: authStateFile(auditSession.sessionMetadata),
+          ...(failedClasses !== undefined && { failedClasses }),
+        },
         distributedConfig,
         pipelineTestingMode,
         logger,
@@ -227,31 +227,13 @@ export class AgentExecutionService {
       agentName,
       auditSession,
       logger,
-      AGENTS[agentName].modelTier,
       customTools,
       path.relative(repoPath, deliverablesPath),
       cancellationSignal,
       submitTool,
     );
 
-    // 6. Spending cap check - defense-in-depth
-    if (result.success && (result.turns ?? 0) <= 2 && (result.cost || 0) === 0) {
-      const resultText = result.result || '';
-      if (isSpendingCapBehavior(result.turns ?? 0, result.cost || 0, resultText)) {
-        return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
-          attemptNumber,
-          result,
-          rollbackReason: 'spending cap detected',
-          errorMessage: `Spending cap likely reached: ${resultText.slice(0, 100)}`,
-          errorCode: ErrorCode.SPENDING_CAP_REACHED,
-          category: 'billing',
-          retryable: true,
-          context: { agentName, turns: result.turns, cost: result.cost },
-        });
-      }
-    }
-
-    // 7. Handle execution failure
+    // 6. Handle execution failure
     if (!result.success) {
       const errorCode = errorCodeFromResult(result);
       return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
@@ -270,39 +252,53 @@ export class AgentExecutionService {
     //       the write→validate→commit sequence is atomic against concurrent sibling agents.
     let commitHash: string | undefined;
     const finalizationError = await withGitRepoLock(async (): Promise<PentestError | null> => {
-      // 8. Write structured output to disk (vuln agents only) from the executor's capture
-      const queueFilename = getQueueFilename(agentName);
-      if (submitTool && queueFilename && result.structuredOutput !== undefined) {
-        await fs.ensureDir(deliverablesPath);
-        const queuePath = path.join(deliverablesPath, queueFilename);
-        await fs.writeFile(queuePath, JSON.stringify(result.structuredOutput, null, 2), 'utf8');
-        logger.info(`Wrote structured output queue to ${queueFilename}`);
-      }
+      // Every step below must surface as a returned error rather than a throw: only the
+      // returned path rolls the workspace back and records the failed attempt.
+      try {
+        // 8. Write structured output to disk (vuln agents only) from the executor's capture
+        const queueFilename = getQueueFilename(agentName);
+        if (submitTool && queueFilename && result.structuredOutput !== undefined) {
+          await fs.ensureDir(deliverablesPath);
+          const queuePath = path.join(deliverablesPath, queueFilename);
+          await fs.writeFile(queuePath, JSON.stringify(result.structuredOutput, null, 2), 'utf8');
+          logger.info(`Wrote structured output queue to ${queueFilename}`);
+        }
 
-      // 9. Validate output
-      const validationPassed = await validateAgentOutput(result, agentName, deliverablesPath, logger);
-      if (!validationPassed) {
+        // 9. Validate output
+        const validationPassed = await validateAgentOutput(result, agentName, deliverablesPath, logger);
+        if (!validationPassed) {
+          return new PentestError(
+            `Agent ${agentName} failed output validation`,
+            'validation',
+            true,
+            { agentName, deliverableFilename: AGENTS[agentName].deliverableFilename },
+            ErrorCode.OUTPUT_VALIDATION_FAILED,
+          );
+        }
+
+        // 10. Render the deliverable to disk so the success commit below stages it
+        if (writeDeliverable) {
+          await writeDeliverable(deliverablesPath);
+        }
+
+        // 11. Success - commit deliverables (scoped) and capture the checkpoint hash
+        const commitResult = await commitGitSuccess(deliverablesPath, agentName, logger, gitPaths);
+        if (!commitResult.success) {
+          return gitFailureForAgent(agentName, 'commit successful results', commitResult.error);
+        }
+        commitHash = commitResult.commitHash;
+        return null;
+      } catch (error) {
+        if (error instanceof PentestError) return error;
+        const errorMessage = error instanceof Error ? error.message : String(error);
         return new PentestError(
-          `Agent ${agentName} failed output validation`,
+          `Agent ${agentName} post-processing failed: ${errorMessage}`,
           'validation',
           true,
-          { agentName, deliverableFilename: AGENTS[agentName].deliverableFilename },
+          { agentName, originalError: errorMessage },
           ErrorCode.OUTPUT_VALIDATION_FAILED,
         );
       }
-
-      // 10. Render the deliverable to disk so the success commit below stages it
-      if (writeDeliverable) {
-        await writeDeliverable(deliverablesPath);
-      }
-
-      // 11. Success - commit deliverables (scoped) and capture the checkpoint hash
-      const commitResult = await commitGitSuccess(deliverablesPath, agentName, logger, gitPaths);
-      if (!commitResult.success) {
-        return gitFailureForAgent(agentName, 'commit successful results', commitResult.error);
-      }
-      commitHash = commitResult.commitHash;
-      return null;
     });
 
     if (finalizationError) {
@@ -326,6 +322,11 @@ export class AgentExecutionService {
       attemptNumber,
       duration_ms: result.duration,
       cost_usd: result.cost || 0,
+      input_tokens: result.inputTokens,
+      output_tokens: result.outputTokens,
+      cache_read_tokens: result.cacheReadTokens,
+      cache_write_tokens: result.cacheWriteTokens,
+      turns: result.turns,
       success: true,
       model: result.model,
       ...(commitHash && { checkpoint: commitHash }),
@@ -353,6 +354,11 @@ export class AgentExecutionService {
       attemptNumber: opts.attemptNumber,
       duration_ms: opts.result.duration,
       cost_usd: opts.result.cost || 0,
+      input_tokens: opts.result.inputTokens,
+      output_tokens: opts.result.outputTokens,
+      cache_read_tokens: opts.result.cacheReadTokens,
+      cache_write_tokens: opts.result.cacheWriteTokens,
+      turns: opts.result.turns,
       success: false,
       model: opts.result.model,
       error: opts.errorMessage,
@@ -406,8 +412,10 @@ export class AgentExecutionService {
   static toMetrics(endResult: AgentEndResult, result: PiPromptResult): AgentMetrics {
     return {
       durationMs: endResult.duration_ms,
-      inputTokens: null, // Not currently exposed by the pi executor
-      outputTokens: null,
+      inputTokens: result.inputTokens ?? null,
+      outputTokens: result.outputTokens ?? null,
+      cacheReadTokens: result.cacheReadTokens ?? null,
+      cacheWriteTokens: result.cacheWriteTokens ?? null,
       costUsd: endResult.cost_usd,
       numTurns: result.turns ?? null,
       model: result.model,

apps/worker/src/services/agent-git-paths.ts

@@ -14,6 +14,7 @@
  */
 
 import { getQueueFilename } from '../ai/queue-schemas.js';
+import { REPORT_JSON_FILENAME, SARIF_FILENAME } from '../paths.js';
 import { AGENTS } from '../session-manager.js';
 import type { AgentName } from '../types/agents.js';
 
@@ -27,5 +28,12 @@ export function getAgentGitPaths(agentName: AgentName): string[] {
   if (queueFilename) {
     paths.push(queueFilename);
   }
+  // The report agent also emits the structured findings the markdown is rendered from, and the
+  // SARIF log when produced. Listing the log unconditionally is harmless when it was not written,
+  // and keeps a stale one from surviving the rollback of a failed attempt.
+  if (agentName === 'report') {
+    paths.push(REPORT_JSON_FILENAME);
+    paths.push(SARIF_FILENAME);
+  }
   return [...new Set(paths)];
 }

apps/worker/src/services/code-location-join.ts

@@ -0,0 +1,78 @@
+// 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.
+
+/**
+ * Attach vuln-queue code locations to collected findings.
+ *
+ * The vuln agent authors `code_locations` once, into its queue. Every stage after that used to
+ * re-transcribe them — the exploit agent into its evidence, the report agent into `add_finding` —
+ * and each hop lost some: 100% in the queue, 98% in the evidence, 42-63% by the report. Nothing
+ * about the copy is a judgement call, and `finding_id` matches the queue `ID` exactly, so the
+ * locations are joined here instead of being asked for again.
+ */
+
+import { fs, path } from 'zx';
+import type { QueueCodeLocation } from '../ai/queue-schemas.js';
+import type { AddFindingInput } from '../collectors/finding-collector.js';
+import type { ActivityLogger } from '../types/activity-logger.js';
+import { ALL_VULN_CLASSES } from '../types/config.js';
+
+interface QueueEntry {
+  ID?: string;
+  code_locations?: QueueCodeLocation[];
+}
+
+/** Read every per-class queue in the deliverables dir into an ID-to-locations map. */
+async function loadQueueLocations(
+  deliverablesPath: string,
+  logger: ActivityLogger,
+): Promise<Map<string, QueueCodeLocation[]>> {
+  const locations = new Map<string, QueueCodeLocation[]>();
+
+  for (const vulnClass of ALL_VULN_CLASSES) {
+    const queuePath = path.join(deliverablesPath, `${vulnClass}_exploitation_queue.json`);
+    if (!(await fs.pathExists(queuePath))) continue;
+
+    try {
+      const doc = (await fs.readJson(queuePath)) as { vulnerabilities?: QueueEntry[] };
+      for (const entry of doc.vulnerabilities ?? []) {
+        if (entry.ID && entry.code_locations && entry.code_locations.length > 0) {
+          locations.set(entry.ID, entry.code_locations);
+        }
+      }
+    } catch (error) {
+      logger.warn(`Could not read ${vulnClass} queue for code locations: ${(error as Error).message}`);
+    }
+  }
+
+  return locations;
+}
+
+/**
+ * Return the findings with `code_locations` filled in from the queue.
+ *
+ * A finding with no matching queue entry keeps none — the join never invents one. Findings are
+ * copied rather than mutated so the collector's own state stays untouched.
+ */
+export async function attachQueueCodeLocations(
+  findings: readonly AddFindingInput[],
+  deliverablesPath: string,
+  logger: ActivityLogger,
+): Promise<AddFindingInput[]> {
+  const byId = await loadQueueLocations(deliverablesPath, logger);
+  if (byId.size === 0) return [...findings];
+
+  let matched = 0;
+  const joined = findings.map((finding) => {
+    const locations = byId.get(finding.finding_id);
+    if (!locations) return finding;
+    matched += 1;
+    return { ...finding, code_locations: locations };
+  });
+
+  logger.info(`Attached code locations to ${matched}/${findings.length} finding(s) from the vuln queues`);
+  return joined;
+}

apps/worker/src/services/config-loader.ts

@@ -38,13 +38,9 @@ export class ConfigLoaderService {
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
 
-      // Determine appropriate error code based on error message
-      let errorCode = ErrorCode.CONFIG_PARSE_ERROR;
-      if (errorMessage.includes('not found') || errorMessage.includes('ENOENT')) {
-        errorCode = ErrorCode.CONFIG_NOT_FOUND;
-      } else if (errorMessage.includes('validation failed')) {
-        errorCode = ErrorCode.CONFIG_VALIDATION_FAILED;
-      }
+      // parseConfig throws PentestErrors that already name the failure; anything
+      // else reaching here is a parse-time fault.
+      const errorCode = error instanceof PentestError && error.code ? error.code : ErrorCode.CONFIG_PARSE_ERROR;
 
       return err(
         new PentestError(

apps/worker/src/services/error-handling.ts

@@ -4,8 +4,8 @@
 // it under the terms of the GNU Affero General Public License version 3
 // as published by the Free Software Foundation.
 
+import { type AssistantMessage, isRetryableAssistantError } from '@earendil-works/pi-ai';
 import { ErrorCode, type PentestErrorContext, type PentestErrorType, type PromptErrorResult } from '../types/errors.js';
-import { matchesBillingApiPattern, matchesBillingTextPattern } from '../utils/billing-detection.js';
 
 export class PentestError extends Error {
   override name = 'PentestError' as const;
@@ -44,53 +44,23 @@ export function handlePromptError(promptName: string, error: Error): PromptError
   };
 }
 
-const RETRYABLE_PATTERNS = [
-  // Network and connection errors
-  'network',
-  'connection',
-  'timeout',
-  'econnreset',
-  'enotfound',
-  'econnrefused',
-  // Rate limiting
-  'rate limit',
-  '429',
-  'too many requests',
-  // Server errors
-  'server error',
-  '5xx',
-  'internal server error',
-  'service unavailable',
-  'bad gateway',
-  // Provider API errors
-  'model unavailable',
-  'service temporarily unavailable',
-  'api error',
-  'terminated',
-  // Max turns
-  'max turns',
-  'maximum turns',
-];
+/**
+ * Whether a failed agent attempt is worth retrying.
+ *
+ * A PentestError already carries a verdict — for provider turns that verdict
+ * comes from pi — so it is taken as given. Anything else is raw text, judged by
+ * pi's classifier: transient for load, throttling, and transport failures,
+ * terminal for quota, billing, and auth. Unrecognised errors are not retried, so
+ * a permanent fault fails fast.
+ */
+export function isRetryableFailure(error: Error): boolean {
+  if (error instanceof PentestError) return error.retryable;
 
-// Patterns that indicate non-retryable errors (checked before default)
-const NON_RETRYABLE_PATTERNS = [
-  'authentication',
-  'invalid prompt',
-  'out of memory',
-  'permission denied',
-  'session limit reached',
-  'invalid api key',
-];
-
-// Conservative retry classification - unknown errors don't retry (fail-safe default)
-export function isRetryableError(error: Error): boolean {
-  const message = error.message.toLowerCase();
-
-  if (NON_RETRYABLE_PATTERNS.some((pattern) => message.includes(pattern))) {
-    return false;
-  }
-
-  return RETRYABLE_PATTERNS.some((pattern) => message.includes(pattern));
+  return isRetryableAssistantError({
+    role: 'assistant',
+    stopReason: 'error',
+    errorMessage: error.message,
+  } as AssistantMessage);
 }
 
 /**
@@ -99,14 +69,6 @@ export function isRetryableError(error: Error): boolean {
  */
 function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { type: string; retryable: boolean } {
   switch (code) {
-    // Billing errors - retryable (wait for cap reset or credits added)
-    case ErrorCode.SPENDING_CAP_REACHED:
-    case ErrorCode.INSUFFICIENT_CREDITS:
-      return { type: 'BillingError', retryable: true };
-
-    case ErrorCode.API_RATE_LIMITED:
-      return { type: 'RateLimitError', retryable: true };
-
     // Config errors - non-retryable (need manual fix)
     case ErrorCode.CONFIG_NOT_FOUND:
     case ErrorCode.CONFIG_VALIDATION_FAILED:
@@ -143,11 +105,10 @@ function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { ty
     case ErrorCode.AUTH_LOGIN_FAILED:
       return { type: 'AuthLoginFailedError', retryable: false };
 
-    case ErrorCode.BILLING_ERROR:
-      return { type: 'BillingError', retryable: true };
+    case ErrorCode.TARGET_UNREACHABLE:
+      return { type: 'InvalidTargetError', retryable: false };
 
     default:
-      // Unknown code - fall through to string matching
       return { type: 'UnknownError', retryable: retryableFromError };
   }
 }
@@ -161,8 +122,8 @@ function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { ty
  * - Non-retryable errors: Temporal fails immediately
  *
  * Classification priority:
- * 1. If error is PentestError with ErrorCode, classify by code (reliable)
- * 2. Fall through to string matching for external errors (provider, network, etc.)
+ * 1. A PentestError carrying an ErrorCode is classified by that code.
+ * 2. Anything else falls through to isRetryableFailure.
  */
 export function classifyErrorForTemporal(error: unknown): { type: string; retryable: boolean } {
   // === CODE-BASED CLASSIFICATION (Preferred for internal errors) ===
@@ -170,101 +131,11 @@ export function classifyErrorForTemporal(error: unknown): { type: string; retrya
     return classifyByErrorCode(error.code, error.retryable);
   }
 
-  // === STRING-BASED CLASSIFICATION (Fallback for external errors) ===
-  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
-
-  // === BILLING ERRORS (Retryable with long backoff) ===
-  // Anthropic returns billing as 400 invalid_request_error
-  // Human can add credits OR wait for spending cap to reset (5-30 min backoff)
-  // Check both API patterns and text patterns for comprehensive detection
-  if (matchesBillingApiPattern(message) || matchesBillingTextPattern(message)) {
-    return { type: 'BillingError', retryable: true };
-  }
-
-  // === PERMANENT ERRORS (Non-retryable) ===
-
-  // Authentication (401) - bad API key won't fix itself
-  if (
-    message.includes('authentication') ||
-    message.includes('api key') ||
-    message.includes('401') ||
-    message.includes('authentication_error')
-  ) {
-    return { type: 'AuthenticationError', retryable: false };
-  }
-
-  // Permission (403) - access won't be granted
-  if (message.includes('permission') || message.includes('forbidden') || message.includes('403')) {
-    return { type: 'PermissionError', retryable: false };
-  }
-
-  // Out of memory - deterministic resource exhaustion, retrying won't help
-  if (message.includes('out of memory')) {
-    return { type: 'OutOfMemoryError', retryable: false };
-  }
-
-  // Invalid prompt - malformed/rejected prompt content won't fix itself on retry
-  if (message.includes('invalid prompt')) {
-    return { type: 'InvalidPromptError', retryable: false };
-  }
-
-  // Session limit reached - distinct from billing/rate-limit; needs manual intervention
-  if (message.includes('session limit reached')) {
-    return { type: 'SessionLimitError', retryable: false };
-  }
-
-  // Overloaded - provider's own error-type token is authoritative regardless of the
-  // HTTP status it arrives under (seen in production under 400, not just 529)
-  if (message.includes('overloaded_error') || message.includes('overloaded')) {
-    return { type: 'OverloadedError', retryable: true };
-  }
-
-  // === OUTPUT VALIDATION ERRORS (Retryable) ===
-  // Agent didn't produce expected deliverables - retry may succeed
-  // IMPORTANT: Must come BEFORE generic 'validation' check below
-  if (message.includes('failed output validation') || message.includes('output validation failed')) {
-    return { type: 'OutputValidationError', retryable: true };
-  }
-
-  // Invalid Request (400) - malformed request is permanent
-  // Note: Checked AFTER billing and AFTER output validation
-  if (message.includes('invalid_request_error') || message.includes('malformed') || message.includes('validation')) {
-    return { type: 'InvalidRequestError', retryable: false };
-  }
-
-  // Request Too Large (413) - won't fit no matter how many retries
-  if (message.includes('request_too_large') || message.includes('too large') || message.includes('413')) {
-    return { type: 'RequestTooLargeError', retryable: false };
-  }
-
-  // Configuration errors - missing files need manual fix
-  if (message.includes('enoent') || message.includes('no such file') || message.includes('cli not installed')) {
-    return { type: 'ConfigurationError', retryable: false };
-  }
-
-  // Execution limits - max turns/budget reached
-  if (
-    message.includes('max turns') ||
-    message.includes('budget') ||
-    message.includes('execution limit') ||
-    message.includes('error_max_turns') ||
-    message.includes('error_max_budget')
-  ) {
-    return { type: 'ExecutionLimitError', retryable: false };
-  }
-
-  // Invalid target URL - bad URL format won't fix itself
-  if (
-    message.includes('invalid url') ||
-    message.includes('invalid target') ||
-    message.includes('malformed url') ||
-    message.includes('invalid uri')
-  ) {
-    return { type: 'InvalidTargetError', retryable: false };
-  }
-
-  // === TRANSIENT ERRORS (Retryable) ===
-  // Rate limits (429), server errors (5xx), network issues
-  // Let Temporal retry with configured backoff
-  return { type: 'TransientError', retryable: true };
+  // === FALLBACK ===
+  // Everything else is a raw throw: a library error, or a PentestError carrying no
+  // code. isRetryableFailure decides — pi's classifier for provider text, the
+  // error's own verdict when it has one, and no retry for anything unrecognised.
+  const err = error instanceof Error ? error : new Error(String(error));
+  const retryable = isRetryableFailure(err);
+  return { type: retryable ? 'TransientError' : 'PermanentError', retryable };
 }

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

@@ -53,9 +53,15 @@ function formatLocation(endpoint: string | undefined, codeLocation: string | und
   return endpoint ?? codeLocation ?? '';
 }
 
+/** The analysis queue carries no severity, so confidence is the only rating. */
+interface CommonEntryFields {
+  readonly confidence: string;
+}
+
 function buildEntry(
   id: string,
   title: string,
+  common: CommonEntryFields,
   summaryRows: ReadonlyArray<string | null>,
   notes: string | undefined,
 ): string {
@@ -63,6 +69,7 @@ function buildEntry(
   lines.push(`### ${id}: ${title}`);
   lines.push('');
   lines.push('**Summary:**');
+  lines.push(`- **Confidence:** ${common.confidence}`);
   for (const row of summaryRows) {
     if (row !== null) lines.push(row);
   }
@@ -79,6 +86,7 @@ function renderAuthEntry(e: AuthFinding): string {
   return buildEntry(
     e.ID,
     e.vulnerability_type,
+    { confidence: e.confidence },
     [
       summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
       summaryRow('Overview', e.missing_defense),
@@ -92,6 +100,7 @@ function renderSsrfEntry(e: SsrfFinding): string {
   return buildEntry(
     e.ID,
     e.vulnerability_type,
+    { confidence: e.confidence },
     [
       summaryRow('Vulnerable location', formatLocation(e.source_endpoint, e.vulnerable_code_location)),
       summaryRow('Overview', e.missing_defense),
@@ -105,6 +114,7 @@ function renderAuthzEntry(e: AuthzFinding): string {
   return buildEntry(
     e.ID,
     e.vulnerability_type,
+    { confidence: e.confidence },
     [
       summaryRow('Vulnerable location', formatLocation(e.endpoint, e.vulnerable_code_location)),
       summaryRow('Overview', e.guard_evidence),
@@ -119,6 +129,7 @@ function renderInjectionEntry(e: InjectionFinding): string {
   return buildEntry(
     e.ID,
     e.vulnerability_type,
+    { confidence: e.confidence },
     [summaryRow('Vulnerable location', location), summaryRow('Overview', e.mismatch_reason)],
     e.notes,
   );
@@ -129,6 +140,7 @@ function renderXssEntry(e: XssFinding): string {
   return buildEntry(
     e.ID,
     e.vulnerability_type,
+    { confidence: e.confidence },
     [summaryRow('Vulnerable location', location), summaryRow('Overview', e.mismatch_reason)],
     e.notes,
   );

apps/worker/src/services/index.ts

@@ -20,4 +20,6 @@ export type { ContainerDependencies } from './container.js';
 export { Container, getContainer, getOrCreateContainer, removeContainer, setContainerFactory } from './container.js';
 export { ExploitationCheckerService } from './exploitation-checker.js';
 export { loadPrompt } from './prompt-manager.js';
+export type { ReportData, ReportMeta } from './report-renderer.js';
+export { renderReport } from './report-renderer.js';
 export { assembleFinalReport, copyReportToRunRoot, injectModelIntoReport } from './reporting.js';

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

@@ -0,0 +1,99 @@
+// 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 { TYPST_BRAND } from '../branding.js';
+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 = TYPST_BRAND;
+
+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

@@ -15,7 +15,7 @@
  * 1. Repository path exists and is a directory
  * 2. Config file parses and validates (if provided)
  * 3. code_path rules match real entries in the repo (filesystem only)
- * 4. Credentials validate via a minimal pi session (API key, OAuth, or Bedrock)
+ * 4. Credentials validate via a minimal pi session against the run's own model
  * 5. Target URL resolves, is not link-local (cloud metadata), and is reachable (DNS + HTTP)
  */
 
@@ -26,22 +26,36 @@ import http from 'node:http';
 import https from 'node:https';
 import net, { type LookupFunction } from 'node:net';
 import os from 'node:os';
+import type { Api, AssistantMessage, Model } from '@earendil-works/pi-ai';
 import {
-  AuthStorage,
+  type AgentSession,
   createAgentSession,
-  ModelRegistry,
+  type ModelRuntime,
   SessionManager,
   SettingsManager,
 } from '@earendil-works/pi-coding-agent';
 import { glob } from 'zx';
-import { resolveEffectiveProvider, resolveModelId } from '../ai/models.js';
+import {
+  type CuratedProviderId,
+  createModelRuntime,
+  GENERIC_API_KEY_ENV,
+  type ModelSpec,
+  type OpenAiFormat,
+  PI_CATALOG_URL,
+  piAuthPresent,
+  resolveGatewayFormat,
+  resolveModel,
+  resolveModelSpec,
+  resolveProviderCredentials,
+} from '../ai/models.js';
+import { PI_RETRY_SETTINGS } from '../ai/pi/retry-settings.js';
+import { providerTurnError } from '../ai/pi/turn-error.js';
 import { parseConfig } from '../config-parser.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
 import type { Config, Rule } from '../types/config.js';
 import { ErrorCode } from '../types/errors.js';
 import { err, isErr, ok, type Result } from '../types/result.js';
-import { matchesBillingTextPattern } from '../utils/billing-detection.js';
-import { PentestError } from './error-handling.js';
+import { isRetryableFailure, PentestError } from './error-handling.js';
 
 const TARGET_URL_TIMEOUT_MS = 10_000;
 
@@ -168,7 +182,7 @@ type RuleKind = 'avoid' | 'focus';
 interface MissingCodePath {
   kind: RuleKind;
   value: string;
-  description: string;
+  description?: string;
 }
 
 async function validateCodePathsExist(
@@ -191,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` +
@@ -215,157 +233,86 @@ async function validateCodePathsExist(
 
 // === Credential Validation ===
 
-/** Map provider error text to a human-readable preflight PentestError. */
-/** Classify a provider error message (thrown or from a failed turn) into a PentestError. */
-function classifyCredentialError(text: string, authType: string): Result<void, PentestError> {
-  const lower = text.toLowerCase();
-  if (matchesBillingTextPattern(text)) {
-    return err(
-      new PentestError(
-        `Anthropic account has a billing or rate-limit issue during ${authType} validation. Add credits or wait and retry.`,
-        'billing',
-        true,
-        { authType },
-        ErrorCode.BILLING_ERROR,
-      ),
-    );
-  }
-  if (/401|403|invalid[ _-]?api[ _-]?key|unauthorized|authentication|forbidden|not allowed|x-api-key/.test(lower)) {
-    return err(
-      new PentestError(
-        `Invalid ${authType}. Check your credentials in .env and try again.`,
-        'config',
-        false,
-        { authType },
-        ErrorCode.AUTH_FAILED,
-      ),
-    );
-  }
-  if (/model/.test(lower) && /not found|not available|unknown/.test(lower)) {
-    return err(
-      new PentestError(
-        `Configured model is not available for this account. Check ANTHROPIC_*_MODEL in .env.`,
-        'config',
-        false,
-        { authType },
-      ),
-    );
-  }
-  if (
-    /network|timeout|enotfound|econnrefused|fetch failed|getaddrinfo|socket|overloaded|unavailable|50\d/.test(lower)
-  ) {
-    return err(
-      new PentestError(`Anthropic API unreachable or temporarily unavailable. Try again shortly.`, 'network', true, {
-        authType,
-      }),
-    );
-  }
-  return err(
-    new PentestError(
-      `${authType} validation failed: ${text.slice(0, 150)}`,
-      'config',
-      false,
-      { authType },
-      ErrorCode.AUTH_FAILED,
-    ),
-  );
-}
-
-/** Minimal pi session probe to validate credentials. An optional baseUrl overrides the endpoint. */
+/**
+ * Minimal pi session probe against the model the scan will use, so credentials the
+ * account cannot use fail here rather than partway through the run. The descriptor
+ * already carries the run's endpoint and wire format, so the probe exercises the
+ * same path the scan will.
+ */
 async function probeCredentialsWithPi(
+  model: Model<Api>,
+  modelRuntime: ModelRuntime,
   authType: string,
-  token?: string,
-  baseUrl?: string,
 ): Promise<Result<void, PentestError>> {
-  const authStorage = AuthStorage.inMemory();
-  if (token) authStorage.setRuntimeApiKey('anthropic', token);
-
-  const baseModel = ModelRegistry.create(authStorage).find('anthropic', resolveModelId('small'));
-  if (!baseModel) {
-    return err(
-      new PentestError(
-        `Model not found in pi registry: ${resolveModelId('small')}`,
-        'config',
-        false,
-        {},
-        ErrorCode.AUTH_FAILED,
-      ),
-    );
-  }
-  const model = baseUrl ? { ...baseModel, baseUrl } : baseModel;
-
-  let errText: string | undefined;
+  let failedTurn: AssistantMessage | undefined;
+  let session: AgentSession | undefined;
   try {
-    const { session } = await createAgentSession({
+    ({ session } = await createAgentSession({
       cwd: os.tmpdir(),
       model,
-      thinkingLevel: 'off',
       noTools: 'all',
-      authStorage,
+      modelRuntime,
       sessionManager: SessionManager.inMemory(),
-      settingsManager: SettingsManager.inMemory({ retry: { enabled: false }, compaction: { enabled: false } }),
-    });
+      settingsManager: SettingsManager.inMemory({ retry: PI_RETRY_SETTINGS, compaction: { enabled: false } }),
+    }));
     session.subscribe((e) => {
       if (e.type === 'turn_end' && e.message.role === 'assistant' && e.message.stopReason === 'error') {
-        errText = e.message.errorMessage ?? 'unknown provider error';
+        failedTurn = e.message;
       }
     });
     await session.prompt('hi');
-    session.dispose();
   } catch (error) {
-    errText = error instanceof Error ? error.message : String(error);
+    const thrown = error instanceof Error ? error : new Error(String(error));
+    return err(
+      new PentestError(
+        `${authType} validation failed: ${thrown.message.slice(0, 300)}`,
+        'unknown',
+        isRetryableFailure(thrown),
+        { authType },
+        ErrorCode.AGENT_EXECUTION_FAILED,
+      ),
+    );
+  } finally {
+    session?.dispose();
   }
 
-  if (errText) return classifyCredentialError(errText, authType);
+  if (failedTurn) return err(providerTurnError(failedTurn, `${authType} validation failed`));
   return ok(undefined);
 }
 
-/** Validate credentials via a minimal pi session. */
+/** 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: 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`;
+}
+
+/** Validate the model selection and its credentials via a minimal pi session. */
 async function validateCredentials(logger: ActivityLogger): Promise<Result<void, PentestError>> {
-  // Resolve the active provider through the same precedence the executor uses, so
-  // preflight validates exactly the credentials the run will use (no drift).
-  const eff = resolveEffectiveProvider();
-
-  // 1. Bedrock mode — validate required AWS credentials are present (pi-ai owns the
-  //    live AWS auth, so there is no cheap session probe here)
-  if (eff.providerId === 'amazon-bedrock') {
-    const required = [
-      'AWS_REGION',
-      'AWS_BEARER_TOKEN_BEDROCK',
-      'ANTHROPIC_SMALL_MODEL',
-      'ANTHROPIC_MEDIUM_MODEL',
-      'ANTHROPIC_LARGE_MODEL',
-    ];
-    const missing = required.filter((v) => !process.env[v]);
-    if (missing.length > 0) {
-      return err(
-        new PentestError(
-          `Bedrock mode requires the following env vars in .env: ${missing.join(', ')}`,
-          'config',
-          false,
-          { missing },
-          ErrorCode.AUTH_FAILED,
-        ),
-      );
-    }
-    logger.info('Bedrock credentials OK');
-    return ok(undefined);
-  }
-
-  // 2. Custom base URL — validate the endpoint via a minimal pi session
-  if (eff.baseUrl) {
-    logger.info('Validating custom base URL');
-    const probe = await probeCredentialsWithPi(`custom endpoint (${eff.baseUrl})`, eff.anthropicToken, eff.baseUrl);
-    if (isErr(probe)) return probe;
-    logger.info('Custom base URL OK');
-    return ok(undefined);
-  }
-
-  // 3. Direct Anthropic — require a credential, then validate via a minimal pi session
-  if (!eff.anthropicToken) {
+  // 1. Resolve the run's model. A malformed spec or unknown provider fails here,
+  //    before any scan work begins.
+  let spec: ModelSpec;
+  try {
+    spec = resolveModelSpec();
+  } catch (error) {
     return err(
       new PentestError(
-        'No API credentials found. Set ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env (or use CLAUDE_CODE_USE_BEDROCK=1 for AWS Bedrock)',
+        error instanceof Error ? error.message : String(error),
         'config',
         false,
         {},
@@ -373,11 +320,78 @@ async function validateCredentials(logger: ActivityLogger): Promise<Result<void,
       ),
     );
   }
+  logger.info(`Model: ${spec.providerId}:${spec.modelId}`);
 
-  const usingApiKey = Boolean(process.env.ANTHROPIC_API_KEY);
-  const authType = usingApiKey ? 'API key' : 'OAuth token';
+  // 2. Credential presence. Bedrock needs both AWS_ vars; every other provider
+  //    needs one API key.
+  const credentials = resolveProviderCredentials(spec.providerId);
+
+  // 3. Wire format for an OpenAI gateway. Rejects a format named where it cannot
+  //    take effect, rather than letting the run proceed on the wrong API.
+  let format: OpenAiFormat;
+  try {
+    format = resolveGatewayFormat(spec.providerId, credentials.baseUrl);
+  } catch (error) {
+    return err(
+      new PentestError(
+        error instanceof Error ? error.message : String(error),
+        'config',
+        false,
+        { providerId: spec.providerId },
+        ErrorCode.AUTH_FAILED,
+      ),
+    );
+  }
+
+  // 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 && !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 ${credentialHint(spec.providerId)} in .env.`,
+        'config',
+        false,
+        { providerId: spec.providerId, ...(missing.length > 0 && { missing }) },
+        ErrorCode.AUTH_FAILED,
+      ),
+    );
+  }
+
+  // 4. Model must exist in the registry, for every provider — Bedrock IDs are the
+  //    easiest to get wrong, since region prefixes and version suffixes differ per
+  //    model (`us.anthropic.claude-opus-5` exists, bare `anthropic.` does not).
+  //    A custom endpoint is exempt: it may serve models under its own names.
+  const modelRuntime = await createModelRuntime(spec.providerId, credentials.apiKey);
+  const baseModel = resolveModel(modelRuntime, spec.providerId, spec.modelId, credentials.baseUrl, format);
+  if (!baseModel) {
+    return err(
+      new PentestError(
+        `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 },
+        ErrorCode.AUTH_FAILED,
+      ),
+    );
+  }
+  if (!modelRuntime.getModel(spec.providerId, spec.modelId)) {
+    logger.warn(
+      `Model "${spec.modelId}" is not in the ${spec.providerId} catalogue; passing it to the custom endpoint as given. Cost figures will be approximate.`,
+    );
+  }
+  if (credentials.baseUrl && spec.providerId === 'openai') {
+    logger.info(`Gateway API: ${format} (${baseModel.api})`);
+  }
+
+  // 5. One real request, so a credential the account cannot use fails here
+  //    rather than partway through the run. Bedrock included: pi resolves the
+  //    bearer token from the primed credential and the region from AWS_REGION,
+  //    so the probe exercises the same auth path the scan will.
+  const authType = describeAuth(spec.providerId, credentials.baseUrl);
   logger.info(`Validating ${authType} via pi...`);
-  const probe = await probeCredentialsWithPi(authType, eff.anthropicToken);
+  const probe = await probeCredentialsWithPi(baseModel, modelRuntime, authType);
   if (isErr(probe)) return probe;
   logger.info(`${authType} OK`);
   return ok(undefined);

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

@@ -8,63 +8,81 @@ import { fs, path } from 'zx';
 import { PROMPTS_DIR } from '../paths.js';
 import { PLAYWRIGHT_SESSION_MAPPING } from '../session-manager.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
-import type { Authentication, DistributedConfig, ReportConfig, Rule, VulnClass } from '../types/config.js';
+import type { Authentication, DistributedConfig, DistributedReportConfig, Rule, VulnClass } from '../types/config.js';
 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.
+ *
+ * A class whose analysis failed was never assessed, so the report must not present its
+ * absence of findings as a clean result. The block is authoritative for that caveat.
+ */
+function renderNotAssessedClassesBlock(failed: readonly VulnClass[] = []): string {
+  if (failed.length === 0) {
+    return '';
+  }
+
+  const classes = [...new Set(failed)];
+  const lines: string[] = [
+    '<not_assessed_classes>',
+    'The following vulnerability classes did not complete and were NOT assessed in this run. Treat this list as authoritative for completeness caveats.',
+    '',
+  ];
+
+  for (const cls of classes) {
+    lines.push(
+      `- ${VULN_CLASS_HEADINGS[cls]}: analysis did not complete; this class was NOT assessed. Absence of findings here does not indicate the class is clean.`,
+    );
+  }
+
+  lines.push(
+    '',
+    'When writing report_meta.executive_summary, scope any no-findings statement to the classes that were assessed and mention these not-assessed classes. Do not state or imply that the target is clean for these classes.',
+    '</not_assessed_classes>',
+  );
+  return lines.join('\n');
+}
+
+/**
+ * Which configured filters this run can actually enforce.
+ *
+ * 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),
+    confidence: Boolean(report?.min_confidence) && !exploitEnabled,
+    guidance: Boolean(report?.guidance?.trim()),
+  };
 }
 
 /**
@@ -72,22 +90,23 @@ function renderVulnSummarySubsections(selected: readonly VulnClass[]): string {
  * each filter is included only when the operator configured it, so the agent
  * never sees `none` placeholders or instructions for filters that don't apply.
  */
-function renderReportFiltersBlock(report: ReportConfig | undefined): string {
+function renderReportFiltersBlock(report: DistributedReportConfig | undefined, exploitEnabled: boolean): string {
   if (!report) return '';
   const guidance = report.guidance?.trim();
-  if (!report.min_severity && !report.min_confidence && !guidance) return '';
+  const applies = applicableFilters(report, exploitEnabled);
+  if (!applies.severity && !applies.confidence && !applies.guidance) return '';
 
   const lines: string[] = [
     '<report_filters>',
     'The filters below are user-supplied and binding for this assessment. Honor each strictly when assembling the final report.',
     '',
   ];
-  if (report.min_severity) {
+  if (applies.severity) {
     lines.push(
       `- Minimum severity: ${report.min_severity} — keep only findings rated this severity or higher (scale: low < medium < high < critical).`,
     );
   }
-  if (report.min_confidence) {
+  if (applies.confidence) {
     lines.push(
       `- Minimum confidence: ${report.min_confidence} — keep only findings rated this confidence or higher (scale: low < medium < high).`,
     );
@@ -106,10 +125,11 @@ function renderReportFiltersBlock(report: ReportConfig | undefined): string {
  * confidence inline as concrete thresholds; guidance is referenced by pointer
  * so the actual text only lives in <report_filters>, avoiding double-statement.
  */
-function renderReportFilterRules(report: ReportConfig | undefined): string {
+function renderReportFilterRules(report: DistributedReportConfig | undefined, exploitEnabled: boolean): string {
+  const applies = applicableFilters(report, exploitEnabled);
   const drops: string[] = [];
-  if (report?.min_severity) drops.push(`* severity is below ${report.min_severity}`);
-  if (report?.min_confidence) drops.push(`* confidence is below ${report.min_confidence}`);
+  if (applies.severity) drops.push(`* severity is below ${report?.min_severity}`);
+  if (applies.confidence) drops.push(`* confidence is below ${report?.min_confidence}`);
   if (report?.guidance?.trim()) drops.push('* topic matches an exclusion in the user guidance');
   if (drops.length === 0) return '';
   return ['   - DROP any `### [TYPE]-VULN-[NUMBER]` finding whose:', ...drops.map((d) => `     ${d}`)].join('\n');
@@ -118,6 +138,8 @@ function renderReportFilterRules(report: ReportConfig | undefined): string {
 interface PromptVariables {
   webUrl: string;
   repoPath: string;
+  /** Classes whose analysis did not complete, so the report can mark them not assessed. */
+  failedClasses?: readonly VulnClass[];
   AUTH_STATE_FILE: string;
   PLAYWRIGHT_SESSION?: string;
 }
@@ -323,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);
     }
@@ -364,19 +386,43 @@ 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,
+      renderNotAssessedClassesBlock(variables.failedClasses ?? []),
+    );
 
     const exploitEnabled = config?.exploit ?? true;
+
+    // Drop every block belonging to the mode this run is not in, so the prompt never documents
+    // a field the tool would reject. The backreference pins each match to a closed pair.
+    const droppedMode = exploitEnabled ? 'analysis' : 'exploit';
+    result = result.replace(new RegExp(`<(${droppedMode}_mode_[a-z_]+)>[\\s\\S]*?</\\1>\\n?`, 'g'), '');
+    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',
     );
 
-    result = replaceLiteral(result, /{{REPORT_FILTERS_BLOCK}}/g, renderReportFiltersBlock(config?.report));
-    result = replaceLiteral(result, /{{REPORT_FILTER_RULES}}/g, renderReportFilterRules(config?.report));
+    if (config?.report?.min_confidence && exploitEnabled) {
+      logger.warn(
+        `report.min_confidence="${config.report.min_confidence}" is ignored when exploit=true: an ` +
+          'exploited finding is rated by severity, not confidence. Use report.min_severity.',
+      );
+    }
+    result = replaceLiteral(
+      result,
+      /{{REPORT_FILTERS_BLOCK}}/g,
+      renderReportFiltersBlock(config?.report, exploitEnabled),
+    );
+    result = replaceLiteral(
+      result,
+      /{{REPORT_FILTER_RULES}}/g,
+      renderReportFilterRules(config?.report, exploitEnabled),
+    );
 
     // Collapse runs of 3+ newlines (left behind by tag-strip and empty-fragment substitutions).
     result = result.replace(/\n{3,}/g, '\n\n');

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

@@ -0,0 +1,301 @@
+// 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.
+
+/**
+ * Deterministic report.json → markdown renderer.
+ *
+ * Converts the structured report output (produced by the finding-collector
+ * tool + set-report-meta CLI) into the same markdown format that the
+ * report agent previously wrote by hand. No LLM in the loop.
+ */
+
+import { BRAND_LOCKUP } from '../branding.js';
+import type { AddFindingInput, AdditionalSection, StepItem, StructuredStep } from '../collectors/finding-collector.js';
+import type { VulnClass } from '../types/config.js';
+
+// ============================================================================
+// TYPES
+// ============================================================================
+
+export interface ReportMeta {
+  readonly target: string;
+  readonly assessment_date: string;
+  readonly scope: string;
+  readonly executive_summary: string;
+  readonly exploit?: boolean;
+  readonly model?: string;
+}
+
+export interface ReportData {
+  readonly report_meta: ReportMeta;
+  readonly findings: readonly AddFindingInput[];
+  // Vuln classes whose pipeline failed and were not assessed this run. Rendered as an explicit
+  // caveat so an un-assessed class is never presented as a clean result.
+  readonly not_assessed?: readonly VulnClass[];
+}
+
+// Without this, an analysis-only report reads as though the impact was demonstrated.
+const ANALYSIS_ONLY_DISCLAIMER = [
+  '> Exploitation was not run for this assessment. Each finding documents a vulnerability',
+  '> identified through analysis; impact is assessed rather than demonstrated, and no live',
+  '> exploitation steps or proof of impact are included.',
+].join('\n');
+
+const NOT_ASSESSED_LABELS: Record<VulnClass, string> = {
+  auth: 'Authentication',
+  authz: 'Authorization',
+  xss: 'Cross-Site Scripting (XSS)',
+  injection: 'SQL/Command Injection',
+  ssrf: 'Server-Side Request Forgery (SSRF)',
+};
+
+function renderNotAssessedSection(notAssessed: readonly VulnClass[]): string {
+  const lines: string[] = ['## Not Assessed', ''];
+  lines.push(
+    'The following vulnerability classes were NOT assessed in this run because their analysis did ' +
+      'not complete. Absence of findings for these classes does not indicate they are clean — re-run ' +
+      'to assess them:',
+  );
+  lines.push('');
+  for (const cls of notAssessed) {
+    lines.push(`- ${NOT_ASSESSED_LABELS[cls]} — analysis did not complete; not assessed.`);
+  }
+  return lines.join('\n');
+}
+
+// ============================================================================
+// STEP ITEM RENDERING
+// ============================================================================
+
+function renderStepItem(item: StepItem): string {
+  if (item.kind === 'prose') {
+    return item.text;
+  }
+  const lang = item.block.language || '';
+  return `\`\`\`${lang}\n${item.block.content}\n\`\`\``;
+}
+
+function renderStepItems(items: readonly StepItem[]): string {
+  return items.map(renderStepItem).join('\n\n');
+}
+
+function renderStructuredStep(step: StructuredStep, index: number): string {
+  const lines: string[] = [];
+  const title = step.title ? `**Step ${index + 1}: ${step.title}**` : `**Step ${index + 1}**`;
+  lines.push(title);
+  lines.push('');
+  lines.push(renderStepItems(step.items));
+  return lines.join('\n');
+}
+
+function renderAdditionalSection(section: AdditionalSection): string {
+  const lines: string[] = [];
+  lines.push(`#### ${section.heading}`);
+  lines.push('');
+  lines.push(renderStepItems(section.items));
+  return lines.join('\n');
+}
+
+// ============================================================================
+// FINDING RENDERING
+// ============================================================================
+
+function titleCase(s: string): string {
+  return s.charAt(0).toUpperCase() + s.slice(1);
+}
+
+function renderFinding(finding: AddFindingInput, exploitEnabled: boolean): string {
+  const lines: string[] = [];
+
+  // Heading
+  lines.push(`### ${finding.finding_id}: ${finding.title}`);
+  lines.push('');
+
+  // Each row is emitted only when the mode that produced the finding supplied its field.
+  lines.push('**Summary:**');
+  if (finding.severity) {
+    lines.push(`- **Severity:** ${titleCase(finding.severity)}`);
+  }
+  if (finding.confidence) {
+    lines.push(`- **Confidence:** ${titleCase(finding.confidence)}`);
+  }
+  lines.push(`- **OWASP:** ${finding.owasp_category}`);
+  lines.push(`- **Vulnerable location:** ${finding.vulnerable_location}`);
+  if (finding.auth_state) {
+    lines.push(`- **Auth state:** ${finding.auth_state}`);
+  }
+  if (exploitEnabled && finding.status) {
+    lines.push(`- **Status:** ${titleCase(finding.status)}`);
+  }
+  if (finding.prerequisites) {
+    lines.push(`- **Prerequisites:** ${finding.prerequisites}`);
+  }
+  lines.push('');
+
+  // Overview
+  lines.push('**Overview:**');
+  lines.push(finding.overview);
+  lines.push('');
+
+  // Impact
+  lines.push('**Impact:**');
+  lines.push(finding.impact);
+  lines.push('');
+
+  if (finding.exploitation_steps && finding.exploitation_steps.length > 0) {
+    lines.push('**Exploitation Steps:**');
+    lines.push('');
+    for (let i = 0; i < finding.exploitation_steps.length; i++) {
+      lines.push(renderStructuredStep(finding.exploitation_steps[i]!, i));
+      lines.push('');
+    }
+  }
+
+  if (finding.proof_of_impact && finding.proof_of_impact.length > 0) {
+    lines.push('**Proof of Impact:**');
+    lines.push('');
+    lines.push(renderStepItems(finding.proof_of_impact));
+    lines.push('');
+  }
+
+  // Remediation
+  lines.push('**Remediation:**');
+  lines.push(finding.remediation);
+  lines.push('');
+
+  // Notes
+  if (finding.notes && finding.notes.length > 0) {
+    lines.push('**Notes:**');
+    lines.push('');
+    lines.push(renderStepItems(finding.notes));
+    lines.push('');
+  }
+
+  // Additional sections
+  if (finding.additional_sections && finding.additional_sections.length > 0) {
+    for (const section of finding.additional_sections) {
+      lines.push(renderAdditionalSection(section));
+      lines.push('');
+    }
+  }
+
+  return lines.join('\n').trimEnd();
+}
+
+// ============================================================================
+// CATEGORY GROUPING
+// ============================================================================
+
+const CATEGORY_ORDER: readonly string[] = ['Injection', 'XSS', 'Authentication', 'SSRF', 'Authorization'];
+
+function categorySort(a: string, b: string): number {
+  const ai = CATEGORY_ORDER.indexOf(a);
+  const bi = CATEGORY_ORDER.indexOf(b);
+  if (ai !== -1 && bi !== -1) return ai - bi;
+  if (ai !== -1) return -1;
+  if (bi !== -1) return 1;
+  return a.localeCompare(b);
+}
+
+// ============================================================================
+// REPORT RENDERING
+// ============================================================================
+
+export function renderReport(data: ReportData): string {
+  const { report_meta, findings, not_assessed = [] } = data;
+  const notAssessedClasses = [...new Set(not_assessed)];
+  const exploitEnabled = report_meta.exploit ?? true;
+  const sections: string[] = [];
+
+  // 1. Executive Summary
+  sections.push('# Security Assessment Report');
+  sections.push('');
+  sections.push(`*${BRAND_LOCKUP}*`);
+  sections.push('');
+  sections.push('## Executive Summary');
+  sections.push(`- Target: ${report_meta.target}`);
+  sections.push(`- Assessment Date: ${report_meta.assessment_date}`);
+  sections.push(`- Scope: ${report_meta.scope}`);
+  sections.push(`- Exploitation: ${exploitEnabled ? 'enabled' : 'disabled'}`);
+  if (report_meta.model) {
+    sections.push(`- Model: ${report_meta.model}`);
+  }
+  sections.push('');
+  sections.push(report_meta.executive_summary);
+  sections.push('');
+  if (!exploitEnabled) {
+    sections.push(ANALYSIS_ONLY_DISCLAIMER);
+    sections.push('');
+  }
+
+  if (findings.length === 0) {
+    if (notAssessedClasses.length > 0) {
+      // Some classes were not assessed — a blanket "no vulnerabilities" statement would be a false
+      // clean bill of health. Scope the clean statement to assessed classes and list the gaps.
+      sections.push('No vulnerabilities were identified in the classes that were assessed.');
+      sections.push('');
+      sections.push(renderNotAssessedSection(notAssessedClasses));
+    } else {
+      sections.push('No vulnerabilities were identified during this assessment.');
+    }
+    return sections.join('\n').trimEnd() + '\n';
+  }
+
+  if (notAssessedClasses.length > 0) {
+    sections.push(renderNotAssessedSection(notAssessedClasses));
+    sections.push('');
+  }
+
+  // 2. Summary by Vulnerability Type
+  const byCategory = new Map<string, AddFindingInput[]>();
+  for (const f of findings) {
+    const list = byCategory.get(f.category) ?? [];
+    list.push(f);
+    byCategory.set(f.category, list);
+  }
+
+  const sortedCategories = [...byCategory.keys()].sort(categorySort);
+
+  sections.push('## Summary by Vulnerability Type');
+  sections.push('');
+  for (const cat of sortedCategories) {
+    const catFindings = byCategory.get(cat)!;
+    sections.push(`### ${cat}`);
+    sections.push('');
+    for (const f of catFindings) {
+      // 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('');
+  }
+
+  // 3. Per-category finding sections
+  const subheading = exploitEnabled ? 'Successfully Exploited Vulnerabilities' : 'Identified Vulnerabilities';
+  const heading = exploitEnabled ? 'Exploitation Evidence' : 'Findings';
+
+  for (const cat of sortedCategories) {
+    const catFindings = byCategory.get(cat)!;
+    sections.push(`# ${cat} ${heading}`);
+    sections.push('');
+    sections.push(`## ${subheading}`);
+    sections.push('');
+    for (const f of catFindings) {
+      sections.push(renderFinding(f, exploitEnabled));
+      sections.push('');
+    }
+  }
+
+  return sections.join('\n').trimEnd() + '\n';
+}

apps/worker/src/services/reporting.ts

@@ -5,7 +5,15 @@
 // as published by the Free Software Foundation.
 
 import { fs, path } from 'zx';
-import { ASSEMBLED_REPORT_FILENAME, deliverablesDir, FINAL_REPORT_FILENAME, resolveSessionJsonPath } from '../paths.js';
+import {
+  ASSEMBLED_REPORT_FILENAME,
+  ASSEMBLED_REPORT_PDF_FILENAME,
+  deliverablesDir,
+  FINAL_REPORT_MD_FILENAME,
+  FINAL_REPORT_PDF_FILENAME,
+  resolveSessionJsonPath,
+  SARIF_FILENAME,
+} from '../paths.js';
 import type { ActivityLogger } from '../types/activity-logger.js';
 import { ErrorCode } from '../types/errors.js';
 import { PentestError } from './error-handling.js';
@@ -166,9 +174,14 @@ export async function injectModelIntoReport(
 }
 
 /**
- * Surface the assembled report at the run directory's top level as the single
- * human-facing deliverable, so a customer opening the run folder sees only the
- * report. The source stays in the deliverables dir (git-checkpointed, used by resume).
+ * 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). 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
+ * run was analysis-only or `report.sarif` was set to false.
  */
 export async function copyReportToRunRoot(
   repoPath: string,
@@ -176,14 +189,30 @@ export async function copyReportToRunRoot(
   runDir: string,
   logger: ActivityLogger,
 ): Promise<void> {
-  const source = path.join(deliverablesDir(repoPath, deliverablesSubdir), ASSEMBLED_REPORT_FILENAME);
+  const dir = deliverablesDir(repoPath, deliverablesSubdir);
 
-  if (!(await fs.pathExists(source))) {
-    logger.warn(`Final report not found, skipping ${FINAL_REPORT_FILENAME}`);
-    return;
+  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(`PDF report not found, skipping ${FINAL_REPORT_PDF_FILENAME}`);
   }
 
-  const destination = path.join(runDir, FINAL_REPORT_FILENAME);
-  await fs.copy(source, destination, { overwrite: true });
-  logger.info(`Surfaced report at ${destination}`);
+  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);
+  if (await fs.pathExists(sarifSource)) {
+    const sarifDestination = path.join(runDir, SARIF_FILENAME);
+    await fs.copy(sarifSource, sarifDestination, { overwrite: true });
+    logger.info(`Surfaced SARIF log at ${sarifDestination}`);
+  }
 }

apps/worker/src/services/sarif-renderer.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.
+
+/** Deterministic report.json to SARIF 2.1.0 renderer, for `exploit=true` runs only. */
+
+import type { AddFindingInput, CodeLocation } from '../collectors/finding-collector.js';
+import type { ReportData } from './report-renderer.js';
+
+export interface SarifOptions {
+  readonly workspaceName: string;
+}
+
+interface SarifRule {
+  readonly id: string;
+  readonly name: string;
+  readonly shortDescription: { text: string };
+  readonly fullDescription: { text: string };
+  readonly help: { text: string };
+  readonly properties: { tags: string[] };
+}
+
+const TOOL_NAME = 'Shannon';
+const TOOL_URI = 'https://github.com/KeygraphHQ/shannon';
+
+/** Taxonomy identity. A reference resolves the component by name, so this must not be reworded. */
+const OWASP_TAXONOMY_NAME = 'OWASP Top Ten 2025';
+
+/**
+ * One rule per vulnerability class, keyed by `finding.category`.
+ *
+ * Rule IDs are the unit of alert grouping: renaming one detaches every alert filed under it.
+ * `fullDescription` and `help` describe the class, never the instance, and GitHub requires the
+ * `text` of both.
+ */
+const RULES: Record<string, SarifRule> = {
+  Injection: {
+    id: 'shannon/injection',
+    name: 'Injection',
+    shortDescription: { text: 'Injection' },
+    fullDescription: {
+      text: 'Untrusted input reaches an interpreter sink (SQL, OS command, template, file path or deserializer) at a position where it can alter the structure of the statement rather than only supply data.',
+    },
+    help: {
+      text: 'Separate code from data at the sink: bind SQL parameters, pass command arguments as an array, and allowlist file paths. Escaping is a weaker control than parameterisation and breaks whenever the sink context changes.',
+    },
+    properties: { tags: ['security', 'shannon'] },
+  },
+  XSS: {
+    id: 'shannon/xss',
+    name: 'Cross-Site Scripting',
+    shortDescription: { text: 'Cross-Site Scripting' },
+    fullDescription: {
+      text: 'Untrusted input reaches a browser rendering context without the encoding that context requires.',
+    },
+    help: {
+      text: 'Encode at the point of output for the specific context (HTML body, attribute, URL, script or style); no single encoder is correct for all of them. Prefer APIs that treat input as text, such as textContent over innerHTML.',
+    },
+    properties: { tags: ['security', 'shannon'] },
+  },
+  Authentication: {
+    id: 'shannon/auth',
+    name: 'Authentication',
+    shortDescription: { text: 'Authentication' },
+    fullDescription: {
+      text: 'A weakness in credential verification or session lifecycle that lets an attacker assume another identity or retain access they should have lost.',
+    },
+    help: {
+      text: 'Issue a fresh session identifier on every privilege change, set HttpOnly, Secure and SameSite on session cookies, rate-limit credential endpoints, and verify the signature and algorithm of externally issued tokens.',
+    },
+    properties: { tags: ['security', 'shannon'] },
+  },
+  Authorization: {
+    id: 'shannon/authz',
+    name: 'Authorization',
+    shortDescription: { text: 'Authorization' },
+    fullDescription: {
+      text: 'An access control decision is missing, evaluated in the client, or applied at the wrong layer, letting a caller act on resources they do not own.',
+    },
+    help: {
+      text: 'Check ownership and role on the server for every object reference, and enforce it in the data-access layer rather than per route, denying by default. An unguessable identifier is not an access control.',
+    },
+    properties: { tags: ['security', 'shannon'] },
+  },
+  SSRF: {
+    id: 'shannon/ssrf',
+    name: 'Server-Side Request Forgery',
+    shortDescription: { text: 'Server-Side Request Forgery' },
+    fullDescription: {
+      text: 'A server-side request takes its destination from untrusted input, letting an attacker reach hosts the server can see but they cannot.',
+    },
+    help: {
+      text: 'Allowlist destination hosts and schemes, resolve DNS before validating the address so rebinding cannot slip through, and block loopback, private and link-local ranges including cloud metadata. Do not follow redirects.',
+    },
+    properties: { tags: ['security', 'shannon'] },
+  },
+};
+
+const CATEGORY_ORDER: readonly string[] = ['Injection', 'XSS', 'Authentication', 'SSRF', 'Authorization'];
+
+/**
+ * Five severities collapse into SARIF's three usable levels, so `critical` and `high` are
+ * indistinguishable. `security-severity` would separate them but lives on the rule, which would
+ * flatten every finding of a class to one score instead.
+ */
+function severityToLevel(severity: string | undefined): string {
+  switch (severity) {
+    case 'critical':
+    case 'high':
+      return 'error';
+    case 'medium':
+      return 'warning';
+    default:
+      return 'note';
+  }
+}
+
+function toPhysicalLocation(location: CodeLocation) {
+  const region: Record<string, number> = {};
+  if (location.start_line) region.startLine = location.start_line;
+  if (location.end_line) region.endLine = location.end_line;
+
+  return {
+    physicalLocation: {
+      artifactLocation: { uri: location.file },
+      ...(Object.keys(region).length > 0 && { region }),
+    },
+    ...(location.symbol && { logicalLocations: [{ name: location.symbol, kind: 'function' }] }),
+    message: { text: location.role },
+  };
+}
+
+/**
+ * Fall back to the HTTP entry point when a finding names no file: a result with no location is
+ * silently discarded downstream. No `uriBaseId`, since the path does not resolve in the repo.
+ */
+function syntheticLocationFromHttp(finding: AddFindingInput) {
+  if (!finding.http_location) return undefined;
+  let uri = finding.http_location.url;
+  try {
+    const parsed = new URL(finding.http_location.url);
+    uri = `${parsed.pathname}${parsed.hash}`;
+  } catch {}
+  return {
+    physicalLocation: { artifactLocation: { uri } },
+    message: { text: `${finding.http_location.method} ${finding.http_location.url}` },
+  };
+}
+
+function buildMessageMarkdown(finding: AddFindingInput): string {
+  const parts = [`**${finding.title}**`, '', finding.overview, '', '**Impact**', '', finding.impact];
+  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.pdf`');
+  return parts.join('\n');
+}
+
+/**
+ * `owasp_category` is one label, `A05:2025 <separator> Injection`; SARIF wants the id and the name
+ * as separate fields. The enum in ../collectors/finding-collector.ts fixes the shape, so the
+ * separator is dropped by position rather than matched.
+ */
+function splitOwaspCategory(label: string): { id: string; name: string } {
+  const [id, , ...nameParts] = label.split(' ');
+  return { id: id ?? label, name: nameParts.join(' ') };
+}
+
+interface RenderedResult {
+  readonly result: Record<string, unknown>;
+  readonly category: string;
+  readonly owaspId: string;
+}
+
+function renderResult(finding: AddFindingInput, ruleId: string): RenderedResult | null {
+  const codeLocations = finding.code_locations ?? [];
+  const sinks = codeLocations.filter((l) => l.role === 'sink');
+  const related = codeLocations.filter((l) => l.role !== 'sink');
+  const primary = sinks[0] ?? codeLocations[0];
+
+  const locations = primary ? [toPhysicalLocation(primary)] : [syntheticLocationFromHttp(finding)].filter(Boolean);
+  if (locations.length === 0) return null;
+
+  const properties: Record<string, unknown> = { findingId: finding.finding_id };
+  if (finding.http_location?.parameter) properties.parameter = finding.http_location.parameter;
+  if (finding.status) properties.status = finding.status;
+  if (finding.auth_state) properties.authState = finding.auth_state;
+  if (finding.prerequisites) properties.prerequisites = finding.prerequisites;
+
+  const owaspId = splitOwaspCategory(finding.owasp_category).id;
+
+  return {
+    category: finding.category,
+    owaspId,
+    result: {
+      ruleId,
+      level: severityToLevel(finding.severity),
+      message: {
+        text: `${finding.title}. ${finding.overview}`,
+        markdown: buildMessageMarkdown(finding),
+      },
+      locations,
+      ...(related.length > 0 && {
+        relatedLocations: related.map((l, i) => ({ id: i + 1, ...toPhysicalLocation(l) })),
+      }),
+      ...(finding.http_location && {
+        // No `parameters`: SARIF wants a name-to-value map and the deliverable names only the
+        // parameter, so any value here would be invented. It travels in `properties` instead.
+        webRequest: { method: finding.http_location.method, target: finding.http_location.url },
+      }),
+      taxa: [
+        {
+          id: owaspId,
+          toolComponent: { name: OWASP_TAXONOMY_NAME },
+        },
+      ],
+      properties,
+    },
+  };
+}
+
+/** Render a SARIF 2.1.0 log from the structured report. Findings with no location are omitted. */
+export function renderSarif(data: ReportData, options: SarifOptions): string {
+  const { report_meta, findings, not_assessed = [] } = data;
+
+  const rendered: RenderedResult[] = [];
+
+  for (const finding of findings) {
+    const rule = RULES[finding.category];
+    if (!rule) continue;
+    const result = renderResult(finding, rule.id);
+    if (result !== null) rendered.push(result);
+  }
+
+  // Only classes that produced a result are declared, and `ruleIndex` is the position in this list.
+  const usedRules = CATEGORY_ORDER.flatMap((category) => {
+    const rule = RULES[category];
+    if (!rule || !rendered.some((r) => r.category === category)) return [];
+    return [{ category, rule }];
+  });
+  const rules = usedRules.map((u) => u.rule);
+
+  const results: Record<string, unknown>[] = usedRules.flatMap(({ category }, ruleIndex) =>
+    rendered.filter((r) => r.category === category).map((r) => ({ ...r.result, ruleIndex })),
+  );
+
+  const owaspCategories = [...new Set(findings.map((f) => f.owasp_category))]
+    .map(splitOwaspCategory)
+    .filter((c) => rendered.some((r) => r.owaspId === c.id))
+    .sort((a, b) => a.id.localeCompare(b.id));
+
+  const log = {
+    $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: TOOL_NAME,
+            informationUri: TOOL_URI,
+            rules,
+          },
+        },
+        // Scoped to the exploit pipeline: an analysis run of the same target has a different
+        // finding population, which would read as alerts resolved.
+        automationDetails: { id: `shannon/exploit/${options.workspaceName}` },
+        invocations: [
+          {
+            // A failed class produced no results; reporting success would read as resolved alerts.
+            executionSuccessful: not_assessed.length === 0,
+          },
+        ],
+        ...(owaspCategories.length > 0 && {
+          taxonomies: [
+            {
+              name: OWASP_TAXONOMY_NAME,
+              organization: 'OWASP',
+              informationUri: 'https://owasp.org/Top10/',
+              shortDescription: { text: 'OWASP Top Ten 2025 categories.' },
+              taxa: owaspCategories.map((c) => ({ id: c.id, name: c.name })),
+            },
+          ],
+        }),
+        results,
+        properties: { target: report_meta.target, assessmentDate: report_meta.assessment_date },
+      },
+    ],
+  };
+
+  return `${JSON.stringify(log, null, 2)}\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...', {
@@ -145,7 +148,6 @@ export async function validateAuthentication(input: ValidateAuthInput): Promise<
     AGENT_NAME,
     auditSession,
     logger,
-    'medium',
     undefined, // callerTools
     deliverablesSubdir,
     cancellationSignal,
@@ -161,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 }),
@@ -171,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>> {
@@ -206,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/session-manager.ts

@@ -17,7 +17,6 @@ export const AGENTS: Readonly<Record<AgentName, AgentDefinition>> = Object.freez
     prerequisites: [],
     promptTemplate: 'pre-recon-code',
     deliverableFilename: 'pre_recon_deliverable.md',
-    modelTier: 'large',
   },
   recon: {
     name: 'recon',

apps/worker/src/temporal/activities.ts

@@ -25,7 +25,16 @@ import type { ResumeAttempt } from '../audit/metrics-tracker.js';
 import { authStateFile, generateAuditPath, generateSessionJsonPath, type SessionMetadata } from '../audit/utils.js';
 import type { WorkflowSummary } from '../audit/workflow-logger.js';
 import type { CheckpointContext } from '../interfaces/checkpoint-provider.js';
-import { DEFAULT_DELIVERABLES_SUBDIR, deliverablesDir, resolveSessionJsonPath } from '../paths.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';
 import { classifyErrorForTemporal, PentestError } from '../services/error-handling.js';
@@ -34,6 +43,7 @@ import { renderFindingsFromQueues } from '../services/findings-renderer.js';
 import { executeGitCommandWithRetry } from '../services/git-manager.js';
 import { runPreflightChecks } from '../services/preflight.js';
 import type { ExploitationDecision, VulnType } from '../services/queue-validation.js';
+import type { ReportData, ReportMeta } from '../services/report-renderer.js';
 import { assembleFinalReport, copyReportToRunRoot, injectModelIntoReport } from '../services/reporting.js';
 import { validateAuthentication } from '../services/validate-authentication.js';
 import { AGENTS } from '../session-manager.js';
@@ -76,6 +86,10 @@ export interface ActivityInput {
   auditDir?: string;
   promptDir?: string;
   sastSarifPath?: string;
+
+  // Vuln classes whose pipeline failed. Set before the report stage on a partial run so the
+  // report marks them "not assessed" instead of asserting no findings were present.
+  failedClasses?: VulnClass[];
 }
 
 /**
@@ -187,6 +201,7 @@ async function runAgentActivity(
         attemptNumber,
         ...(input.promptDir !== undefined && { promptDir: input.promptDir }),
         ...(input.configYAML !== undefined && { configYAML: input.configYAML }),
+        ...(input.failedClasses !== undefined && { failedClasses: input.failedClasses }),
         ...(customTools && { customTools }),
         ...(writeDeliverable && { writeDeliverable }),
         cancellationSignal: Context.current().cancellationSignal,
@@ -198,10 +213,12 @@ async function runAgentActivity(
     // 4. Return metrics
     return {
       durationMs: Date.now() - startTime,
-      inputTokens: null,
-      outputTokens: null,
+      inputTokens: endResult.input_tokens ?? null,
+      outputTokens: endResult.output_tokens ?? null,
+      cacheReadTokens: endResult.cache_read_tokens ?? null,
+      cacheWriteTokens: endResult.cache_write_tokens ?? null,
       costUsd: endResult.cost_usd,
-      numTurns: null,
+      numTurns: endResult.turns ?? null,
       model: endResult.model,
     };
   } catch (error) {
@@ -432,8 +449,124 @@ export async function runAuthzExploitAgent(input: ActivityInput): Promise<AgentM
   return runExploitAgentWithCollector('authz-exploit', 'authz', input);
 }
 
-export async function runReportAgent(input: ActivityInput): Promise<AgentMetrics> {
-  return runAgentActivity('report', input);
+/**
+ * Write report.sarif for exploitative runs unless the operator opted out with report.sarif: false.
+ *
+ * On by default so a CI step consuming the log always finds one. Skipped for analysis-only runs.
+ * The original reason was that those findings carried no severity, so every `result.level` would
+ * have been invented; since severity is recorded in both modes an analysis run could now populate
+ * `level`, but it would report an assessed severity as a measured one, so the gate stays. Failures
+ * are logged and swallowed — the SARIF log is a secondary artifact and must not fail a run whose
+ * report is already written.
+ */
+async function writeSarifIfEnabled(
+  input: ActivityInput,
+  exploit: boolean,
+  reportData: ReportData,
+  deliverablesPath: string,
+  logger: ReturnType<typeof createActivityLogger>,
+): Promise<void> {
+  if (!exploit) return;
+
+  const container = getOrCreateContainer(input.workflowId, buildSessionMetadata(input), buildContainerConfig(input));
+  const configResult = await container.configLoader.loadOptional(input.configPath, undefined, input.configYAML);
+  // Only an explicit false opts out; a missing config keeps the default on.
+  if (isErr(configResult) || configResult.value?.report?.sarif === false) return;
+
+  try {
+    const { renderSarif } = await import('../services/sarif-renderer.js');
+    const sarif = renderSarif(reportData, { workspaceName: input.sessionId });
+    await atomicWrite(path.join(deliverablesPath, SARIF_FILENAME), sarif);
+    logger.info(`Wrote ${SARIF_FILENAME}`);
+  } catch (error) {
+    logger.warn(`Failed to write ${SARIF_FILENAME}: ${(error as Error).message}`);
+  }
+}
+
+/**
+ * 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');
+
+  const collector = createFindingCollector(exploit);
+
+  const writeDeliverable = async (deliverablesPath: string): Promise<void> => {
+    const logger = createActivityLogger();
+    const { attachQueueCodeLocations } = await import('../services/code-location-join.js');
+    const collected = collector.getAll();
+    logger.info(`Collected ${collected.length} finding(s) from report agent`);
+    const findings = await attachQueueCodeLocations(collected, deliverablesPath, logger);
+
+    // report_meta is written by the set-report-meta CLI while the agent runs; read it back so
+    // the two halves of report.json end up in one document.
+    const reportJsonPath = path.join(deliverablesPath, REPORT_JSON_FILENAME);
+    let reportMeta: ReportMeta = {
+      target: input.webUrl,
+      assessment_date: new Date().toISOString().split('T')[0]!,
+      scope: '',
+      executive_summary: '',
+      exploit,
+    };
+    if (await fileExists(reportJsonPath)) {
+      try {
+        const existing = await readJson<{ report_meta?: Record<string, unknown> }>(reportJsonPath);
+        if (existing.report_meta) {
+          reportMeta = {
+            target: String(existing.report_meta.target ?? input.webUrl),
+            assessment_date: String(existing.report_meta.assessment_date ?? reportMeta.assessment_date),
+            scope: String(existing.report_meta.scope ?? ''),
+            executive_summary: String(existing.report_meta.executive_summary ?? ''),
+            // Run scope, not agent output — keeps the rendered report and the schema the agent
+            // was given in agreement.
+            exploit,
+            ...(existing.report_meta.model !== undefined && { model: String(existing.report_meta.model) }),
+          };
+        }
+      } catch {
+        logger.warn('Failed to read report_meta from report.json, using defaults');
+      }
+    }
+
+    const reportData: ReportData = {
+      report_meta: reportMeta,
+      findings,
+      ...(input.failedClasses && input.failedClasses.length > 0 && { not_assessed: input.failedClasses }),
+    };
+
+    await atomicWrite(reportJsonPath, JSON.stringify(reportData, null, 2));
+    logger.info(`Wrote ${REPORT_JSON_FILENAME} with ${findings.length} finding(s)`);
+
+    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);
+  };
+
+  return runAgentActivity('report', input, collector.tools, writeDeliverable);
 }
 
 /**
@@ -508,7 +641,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;
 
@@ -526,13 +659,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);
@@ -571,6 +704,8 @@ export async function runAuthenticationValidation(input: ActivityInput): Promise
       truncateStackTrace(failure);
       throw failure;
     }
+
+    return result.value;
   } catch (error) {
     if (error instanceof ApplicationFailure) {
       throw error;
@@ -1009,9 +1144,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[],
@@ -1020,10 +1165,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/pipeline.ts

@@ -14,5 +14,4 @@ export type {
   ResumeState,
   VulnExploitPipelineResult,
 } from './shared.js';
-export { PipelineExecutionError } from './shared.js';
 export { pentestPipeline } from './workflows.js';

apps/worker/src/temporal/shared.ts

@@ -2,7 +2,7 @@ import { defineQuery } from '@temporalio/workflow';
 
 export type { AgentMetrics } from '../types/metrics.js';
 
-import type { DistributedConfig, PipelineConfig, VulnClass } from '../types/config.js';
+import type { DistributedConfig, VulnClass } from '../types/config.js';
 import type { ErrorCode } from '../types/errors.js';
 import type { AgentMetrics } from '../types/metrics.js';
 
@@ -12,7 +12,6 @@ export interface PipelineInput {
   configPath?: string;
   outputPath?: string;
   pipelineTestingMode?: boolean;
-  pipelineConfig?: PipelineConfig;
   workflowId?: string; // Used for audit correlation
   sessionId?: string; // Workspace directory name (distinct from workflowId for named workspaces)
   resumeFromWorkspace?: string; // Workspace name to resume from
@@ -61,21 +60,6 @@ export interface PipelineState {
   summary: PipelineSummary | null;
 }
 
-/**
- * Thrown by pentestPipeline() when the run fails, carrying the fully-populated
- * PipelineState (real agentMetrics, completedAgents, summary) so a consumer can
- * report actual spend instead of synthesizing a zeroed failed state. `cause`
- * preserves the original error for classification and Temporal failure reporting.
- */
-export class PipelineExecutionError extends Error {
-  override name = 'PipelineExecutionError' as const;
-  readonly state: PipelineState;
-  constructor(message: string, state: PipelineState, options?: { cause?: unknown }) {
-    super(message, options);
-    this.state = state;
-  }
-}
-
 // Extended state returned by getProgress query (includes computed fields)
 export interface PipelineProgress extends PipelineState {
   workflowId: string;

apps/worker/src/temporal/worker.ts

@@ -35,8 +35,13 @@ 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 type { PipelineConfig, VulnClass } from '../types/config.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';
 import type { PipelineInput, PipelineProgress, PipelineState } from './shared.js';
@@ -276,26 +281,16 @@ async function resolveWorkspace(client: Client, args: CliArgs): Promise<Workspac
 // === Pipeline Input Construction ===
 
 interface OrchestrationConfig {
-  pipelineConfig: PipelineConfig;
   vulnClasses?: VulnClass[];
   exploit?: boolean;
 }
 
 async function loadOrchestrationConfig(configPath: string | undefined): Promise<OrchestrationConfig> {
-  if (!configPath) return { pipelineConfig: {} };
+  if (!configPath) return {};
   try {
     const config = await parseConfig(configPath);
 
-    const pipelineConfig: PipelineConfig = {};
-    if (config.pipeline?.retry_preset !== undefined) {
-      pipelineConfig.retry_preset = config.pipeline.retry_preset;
-    }
-    if (config.pipeline?.max_concurrent_pipelines !== undefined) {
-      pipelineConfig.max_concurrent_pipelines = Number(config.pipeline.max_concurrent_pipelines);
-    }
-
     return {
-      pipelineConfig,
       ...(config.vuln_classes && config.vuln_classes.length > 0 && { vulnClasses: [...config.vuln_classes] }),
       ...(config.exploit !== undefined && { exploit: config.exploit === 'true' }),
     };
@@ -322,7 +317,6 @@ function buildPipelineInput(
     ...(args.pipelineTestingMode && { pipelineTestingMode: args.pipelineTestingMode }),
     ...(workspace.isResume && args.resumeFromWorkspace && { resumeFromWorkspace: args.resumeFromWorkspace }),
     ...(workspace.terminatedWorkflows.length > 0 && { terminatedWorkflows: workspace.terminatedWorkflows }),
-    ...(Object.keys(orchestration.pipelineConfig).length > 0 && { pipelineConfig: orchestration.pipelineConfig }),
     ...(orchestration.vulnClasses && { vulnClasses: orchestration.vulnClasses }),
     ...(orchestration.exploit !== undefined && { exploit: orchestration.exploit }),
   };
@@ -400,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/workflow-errors.ts

@@ -21,8 +21,6 @@ import { ErrorCode } from '../types/errors.js';
  */
 const ERROR_TYPE_TO_CODE: Record<string, ErrorCode> = {
   AuthenticationError: ErrorCode.AUTH_FAILED,
-  BillingError: ErrorCode.BILLING_ERROR,
-  RateLimitError: ErrorCode.API_RATE_LIMITED,
   ConfigurationError: ErrorCode.CONFIG_VALIDATION_FAILED,
   OutputValidationError: ErrorCode.OUTPUT_VALIDATION_FAILED,
   AgentExecutionError: ErrorCode.AGENT_EXECUTION_FAILED,
@@ -44,13 +42,10 @@ export function classifyErrorCode(error: unknown): ErrorCode | undefined {
 
 /** Maps Temporal error type strings to actionable remediation hints. */
 const REMEDIATION_HINTS: Record<string, string> = {
-  AuthenticationError: 'Verify ANTHROPIC_API_KEY or CLAUDE_CODE_OAUTH_TOKEN in .env is valid and not expired.',
+  AuthenticationError: "Verify the selected provider's API key is valid and not expired.",
   ConfigurationError: 'Check your CONFIG file path and contents.',
-  BillingError: 'Check your Anthropic billing dashboard. Add credits or wait for spending cap reset.',
   GitError: 'Check repository path and git state.',
   InvalidTargetError: 'Verify the target URL is correct and accessible.',
-  PermissionError: 'Check file and network permissions.',
-  ExecutionLimitError: 'Agent exceeded maximum turns or budget. Review prompt complexity.',
 };
 
 /**

apps/worker/src/temporal/workflows.ts

@@ -17,13 +17,14 @@
  *
  * Features:
  * - Queryable state via getProgress
- * - Automatic retry with backoff for transient/billing errors
+ * - Automatic retry with backoff for transient errors
  * - Non-retryable classification for permanent errors
  * - Audit correlation via workflowId
  * - Graceful failure handling: pipelines continue if one fails
  */
 
 import {
+  ActivityCancellationType,
   ApplicationFailure,
   CancellationScope,
   isCancellation,
@@ -40,7 +41,6 @@ import type { ActivityInput } from './activities.js';
 import {
   type AgentMetrics,
   getProgress,
-  PipelineExecutionError,
   type PipelineInput,
   type PipelineProgress,
   type PipelineState,
@@ -64,21 +64,21 @@ function computeExpectedAgents(vulnClasses: readonly VulnClass[], exploit: boole
   return expected;
 }
 
-// Retry configuration for production (long intervals for billing recovery)
+// Retry configuration for production (long intervals so a rate-limit window can clear)
 const PRODUCTION_RETRY = {
   initialInterval: '5 minutes',
   maximumInterval: '30 minutes',
   backoffCoefficient: 2,
   maximumAttempts: 50,
+  // Belt-and-braces: activities already throw non-retryable ApplicationFailures for
+  // these. Only types that are always permanent belong here — GitError and
+  // AgentExecutionError carry a per-error verdict and must not be listed.
   nonRetryableErrorTypes: [
     'AuthenticationError',
-    'PermissionError',
-    'InvalidRequestError',
-    'RequestTooLargeError',
     'ConfigurationError',
     'InvalidTargetError',
-    'ExecutionLimitError',
     'AuthLoginFailedError',
+    'PermanentError',
   ],
 };
 
@@ -96,6 +96,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,22 +105,7 @@ const testActs = proxyActivities<typeof activities>({
   startToCloseTimeout: '30 minutes',
   heartbeatTimeout: '30 minutes', // Extended for sub-agent execution in testing
   retry: TESTING_RETRY,
-});
-
-// Retry configuration for subscription plans (5h+ rolling rate limit windows)
-const SUBSCRIPTION_RETRY = {
-  initialInterval: '5 minutes',
-  maximumInterval: '6 hours',
-  backoffCoefficient: 2,
-  maximumAttempts: 100,
-  nonRetryableErrorTypes: PRODUCTION_RETRY.nonRetryableErrorTypes,
-};
-
-// Activity proxy for subscription plan recovery (extended timeouts)
-const subscriptionActs = proxyActivities<typeof activities>({
-  startToCloseTimeout: '8 hours',
-  heartbeatTimeout: '2 hours',
-  retry: SUBSCRIPTION_RETRY,
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 // Retry configuration for preflight validation (short timeout, few retries)
@@ -135,6 +122,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.
@@ -151,6 +139,7 @@ const authValidationActs = proxyActivities<typeof activities>({
   startToCloseTimeout: '10 minutes',
   heartbeatTimeout: '10 minutes',
   retry: AUTH_VALIDATION_RETRY,
+  cancellationType: ActivityCancellationType.TRY_CANCEL,
 });
 
 /**
@@ -167,6 +156,9 @@ function computeSummary(state: PipelineState): PipelineSummary {
   };
 }
 
+/** One pipeline per vulnerability class, all five in flight together. */
+const MAX_CONCURRENT_PIPELINES = 5;
+
 const MAX_PIPELINE_ERROR_MESSAGE_LENGTH = 2000;
 
 function truncatePipelineErrorMessage(message: string): string {
@@ -200,14 +192,7 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
 
   const { workflowId } = workflowInfo();
 
-  // Select activity proxy based on mode: testing (fast), subscription (extended), or default
-  function selectActivityProxy(pipelineInput: PipelineInput) {
-    if (pipelineInput.pipelineTestingMode) return testActs;
-    if (pipelineInput.pipelineConfig?.retry_preset === 'subscription') return subscriptionActs;
-    return acts;
-  }
-
-  const a = selectActivityProxy(input);
+  const a = input.pipelineTestingMode ? testActs : acts;
 
   const state: PipelineState = {
     status: 'running',
@@ -266,6 +251,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,
@@ -297,10 +286,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,
@@ -500,7 +488,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');
 
@@ -611,8 +603,6 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
       }
     }
 
-    const maxConcurrent = input.pipelineConfig?.max_concurrent_pipelines ?? 5;
-
     const pipelineConfigs = buildPipelineConfigs();
     const pipelineThunks: Array<() => Promise<VulnExploitPipelineResult>> = [];
     let alreadyCompletedPipelineCount = 0;
@@ -632,9 +622,15 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
       }
     }
 
-    const pipelineResults = await runWithConcurrencyLimit(pipelineThunks, maxConcurrent);
+    const pipelineResults = await runWithConcurrencyLimit(pipelineThunks, MAX_CONCURRENT_PIPELINES);
     aggregatePipelineResults(pipelineResults, alreadyCompletedPipelineCount);
 
+    // Surface the not-assessed classes to the report stage so a failed class renders as
+    // "analysis did not complete" rather than the absence assertion "no findings".
+    if (state.failedPipelines.length > 0) {
+      activityInput.failedClasses = state.failedPipelines.map((f) => f.vulnType);
+    }
+
     state.currentPhase = 'exploitation';
     state.currentAgent = null;
     await a.logPhaseTransition(activityInput, 'vulnerability-exploitation', 'complete');
@@ -649,7 +645,7 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
       await a.assembleReportActivity(activityInput, exploit);
 
       // Then run the report agent to add executive summary and clean up
-      state.agentMetrics.report = await a.runReportAgent(activityInput);
+      state.agentMetrics.report = await a.runReportAgent(activityInput, exploit);
       state.completedAgents.push('report');
       if (input.checkpointsEnabled) {
         await a.saveCheckpoint(activityInput, 'report', 'reporting', state);
@@ -721,9 +717,10 @@ export async function pentestPipeline(input: PipelineInput): Promise<PipelineSta
       });
     }
 
-    // Carry the populated state so a consumer can report real spend instead of a zeroed
-    // failed state. The original error rides as `cause` for classification/reporting.
-    throw new PipelineExecutionError(state.error ?? 'Pipeline failed', state, { cause: error });
+    // Terminate the workflow in Temporal's FAILED state. WARNING: this must be an
+    // ApplicationFailure — any other thrown type becomes an unhandled workflow-task failure
+    // that Temporal retries indefinitely, leaving the run stuck in RUNNING.
+    throw ApplicationFailure.nonRetryable(state.error ?? 'Pipeline failed', 'PipelineExecutionError');
   }
 }
 

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/agents.ts

@@ -48,7 +48,6 @@ export interface AgentDefinition {
   prerequisites: AgentName[];
   promptTemplate: string;
   deliverableFilename: string;
-  modelTier?: 'small' | 'medium' | 'large';
 }
 
 /**

apps/worker/src/types/audit.ts

@@ -27,6 +27,11 @@ export interface AgentEndResult {
   attemptNumber: number;
   duration_ms: number;
   cost_usd: number;
+  input_tokens?: number | undefined;
+  output_tokens?: number | undefined;
+  cache_read_tokens?: number | undefined;
+  cache_write_tokens?: number | undefined;
+  turns?: number | undefined;
   success: boolean;
   model?: string | undefined;
   error?: string | undefined;

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;
 }
@@ -32,6 +32,11 @@ export interface ReportConfig {
   min_severity?: Severity;
   min_confidence?: Confidence;
   guidance?: string;
+  /**
+   * Emit report.sarif alongside the markdown report. On by default for exploit runs; set 'false'
+   * to opt out. Ignored when exploit is false.
+   */
+  sarif?: 'true' | 'false';
 }
 
 export type LoginType = 'form' | 'sso' | 'api' | 'basic';
@@ -65,7 +70,6 @@ export interface Authentication {
 export interface Config {
   rules?: Rules;
   authentication?: Authentication;
-  pipeline?: PipelineConfig;
   description?: string;
   vuln_classes?: VulnClass[];
   exploit?: 'true' | 'false';
@@ -73,12 +77,8 @@ export interface Config {
   rules_of_engagement?: string;
 }
 
-export type RetryPreset = 'default' | 'subscription';
-
-export interface PipelineConfig {
-  retry_preset?: RetryPreset;
-  max_concurrent_pipelines?: number;
-}
+/** Report config after coercion. The YAML form of `sarif` is a string (see ReportConfig). */
+export type DistributedReportConfig = Omit<ReportConfig, 'sarif'> & { sarif: boolean };
 
 export interface DistributedConfig {
   avoid: Rule[];
@@ -87,7 +87,7 @@ export interface DistributedConfig {
   description: string;
   vuln_classes: VulnClass[];
   exploit: boolean;
-  report: ReportConfig;
+  report: DistributedReportConfig;
   rules_of_engagement: string;
 }
 

apps/worker/src/types/errors.ts

@@ -25,11 +25,6 @@ export enum ErrorCode {
   AGENT_EXECUTION_FAILED = 'AGENT_EXECUTION_FAILED',
   OUTPUT_VALIDATION_FAILED = 'OUTPUT_VALIDATION_FAILED',
 
-  // Billing errors (PentestErrorType: 'billing')
-  API_RATE_LIMITED = 'API_RATE_LIMITED',
-  SPENDING_CAP_REACHED = 'SPENDING_CAP_REACHED',
-  INSUFFICIENT_CREDITS = 'INSUFFICIENT_CREDITS',
-
   // Git errors (PentestErrorType: 'filesystem')
   GIT_CHECKPOINT_FAILED = 'GIT_CHECKPOINT_FAILED',
   GIT_ROLLBACK_FAILED = 'GIT_ROLLBACK_FAILED',
@@ -45,10 +40,9 @@ export enum ErrorCode {
   TARGET_UNREACHABLE = 'TARGET_UNREACHABLE',
   AUTH_FAILED = 'AUTH_FAILED',
   AUTH_LOGIN_FAILED = 'AUTH_LOGIN_FAILED',
-  BILLING_ERROR = 'BILLING_ERROR',
 }
 
-export type PentestErrorType = 'config' | 'network' | 'prompt' | 'filesystem' | 'validation' | 'billing' | 'unknown';
+export type PentestErrorType = 'config' | 'network' | 'prompt' | 'filesystem' | 'validation' | 'unknown';
 
 export interface PentestErrorContext {
   [key: string]: unknown;

apps/worker/src/types/metrics.ts

@@ -13,6 +13,8 @@ export interface AgentMetrics {
   durationMs: number;
   inputTokens: number | null;
   outputTokens: number | null;
+  cacheReadTokens: number | null;
+  cacheWriteTokens: number | null;
   costUsd: number | null;
   numTurns: number | null;
   model?: string | undefined;

apps/worker/src/utils/billing-detection.ts

@@ -1,90 +0,0 @@
-// 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.
-
-/**
- * Consolidated billing/spending cap detection utilities.
- *
- * Anthropic's spending cap behavior is inconsistent:
- * - Sometimes a proper provider error (billing_error)
- * - Sometimes the model responds with text about the cap
- * - Sometimes partial billing before cutoff
- *
- * This module provides defense-in-depth detection with shared pattern lists
- * to prevent drift between detection points.
- */
-
-/**
- * Text patterns for model-output sniffing (what the model says).
- * Used by the pi executor and the behavioral heuristic.
- */
-export const BILLING_TEXT_PATTERNS = [
-  'spending cap',
-  'spending limit',
-  'cap reached',
-  'budget exceeded',
-  'usage limit',
-] as const;
-
-/**
- * API patterns for error message classification (what the API returns).
- * Used by classifyErrorForTemporal in error-handling.ts.
- */
-export const BILLING_API_PATTERNS = [
-  'billing_error',
-  'credit balance is too low',
-  'insufficient credits',
-  'usage is blocked due to insufficient credits',
-  'please visit plans & billing',
-  'please visit plans and billing',
-  'usage limit reached',
-  'quota exceeded',
-  'daily rate limit',
-  'limit will reset',
-  'billing limit reached',
-] as const;
-
-/**
- * Checks if text matches any billing text pattern.
- * Used for sniffing model output content for spending cap messages.
- */
-export function matchesBillingTextPattern(text: string): boolean {
-  const lowerText = text.toLowerCase();
-  return BILLING_TEXT_PATTERNS.some((pattern) => lowerText.includes(pattern));
-}
-
-/**
- * Checks if an error message matches any billing API pattern.
- * Used for classifying API error messages.
- */
-export function matchesBillingApiPattern(message: string): boolean {
-  const lowerMessage = message.toLowerCase();
-  return BILLING_API_PATTERNS.some((pattern) => lowerMessage.includes(pattern));
-}
-
-/**
- * Behavioral heuristic for detecting spending cap.
- *
- * When the model hits a spending cap, it often returns a short message
- * with $0 cost. Legitimate agent work NEVER costs $0 with only 1-2 turns.
- *
- * This combines three signals:
- * 1. Very low turn count (<=2)
- * 2. Zero cost ($0)
- * 3. Text matches billing patterns
- *
- * @param turns - Number of turns the agent took
- * @param cost - Total cost in USD
- * @param resultText - The result text from the agent
- * @returns true if this looks like a spending cap hit
- */
-export function isSpendingCapBehavior(turns: number, cost: number, resultText: string): boolean {
-  // Only check if turns <= 2 AND cost is exactly 0
-  if (turns > 2 || cost !== 0) {
-    return false;
-  }
-
-  return matchesBillingTextPattern(resultText);
-}