feat: bump pi harness to 0.84.2 to enable xAI subscription auth (#435)

* docs: rebuild the npm package README on the main README's identity

* docs: point the README banner fallback at an asset that exists

* docs: declare the npm package author, homepage, and issue tracker

* docs(cli): retire "Framework" and settle on the canonical product line

* docs: describe the banner image in alt text instead of repeating the lockup

* feat(cli): print a plain-text banner when stdout is not a terminal

* feat(report): attribute the markdown report from a shared brand constant

* feat(cli): frame the plain-text banner with rules and split the version line

* docs: drop the URL from the npm author field

.env.example

@@ -1,66 +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.
 
-# Recommended output token configuration for larger tool outputs
-CLAUDE_CODE_MAX_OUTPUT_TOKENS=64000
-
-# 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/Vertex.
-# 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
 
-# =============================================================================
-# OPTION 4: Google Vertex AI
-# =============================================================================
-# https://cloud.google.com/vertex-ai/generative-ai/docs/partner-models/use-partner-models
-# Requires a GCP service account with roles/aiplatform.user.
-# Download the SA key JSON from GCP Console (IAM > Service Accounts > Keys).
-# Requires the model tier overrides above to be set with Vertex AI model IDs.
-# Example Vertex AI model IDs:
-#   ANTHROPIC_SMALL_MODEL=claude-haiku-4-5@20251001
-#   ANTHROPIC_MEDIUM_MODEL=claude-sonnet-4-6
-#   ANTHROPIC_LARGE_MODEL=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.
 
-# CLAUDE_CODE_USE_VERTEX=1
-# CLOUD_ML_REGION=us-east5
-# ANTHROPIC_VERTEX_PROJECT_ID=your-gcp-project-id
-# GOOGLE_APPLICATION_CREDENTIALS=./credentials/google-sa-key.json
+# 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"

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/claude-executor.ts` — Claude Agent SDK integration with retry logic
+- `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 written into `~/.claude/settings.json` `permissions.deny` (`Read`/`Edit`) once per workflow by `apps/worker/src/temporal/activities.ts:syncCodePathDenyRules` so the SDK enforces them at the tool layer even in `bypassPermissions` mode. `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
-- **SDK Integration** — Uses `@anthropic-ai/claude-agent-sdk` with `maxTurns: 10_000` and `bypassPermissions` mode. Adaptive thinking is enabled by default on Opus 4.6/4.7/4.8 (`supportsAdaptiveThinking` in `apps/worker/src/ai/models.ts`); disable per-scan via `CLAUDE_ADAPTIVE_THINKING=false` (env) or `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
 
@@ -173,7 +176,7 @@ Durable workflow orchestration with crash recovery, queryable progress, intellig
 ### Key Design Patterns
 - **Configuration-Driven** — YAML configs with JSON Schema validation
 - **Progressive Analysis** — Each phase builds on previous results
-- **SDK-First** — Claude Agent SDK handles autonomous analysis
+- **Harness-First** — the pi harness (`@earendil-works/pi-coding-agent`) handles autonomous analysis
 - **Modular Error Handling** — `ErrorCode` enum, `Result<T,E>` for explicit error propagation, automatic retry (3 attempts per agent)
 - **Services Boundary** — Activities are thin Temporal wrappers; `apps/worker/src/services/` owns business logic, accepts `ActivityLogger`, returns `Result<T,E>`. No Temporal imports in services
 - **DI Container** — Per-workflow in `apps/worker/src/services/container.ts`. `AuditSession` excluded (parallel safety)
@@ -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/claude-executor.ts`, `apps/worker/src/ai/settings-writer.ts` (writes `code_path` deny rules to `~/.claude/settings.json`), `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
@@ -91,7 +109,7 @@ COPY --from=builder /app/node_modules /app/node_modules
 COPY --from=builder /app/apps/worker /app/apps/worker
 COPY --from=builder /app/apps/cli/package.json /app/apps/cli/package.json
 
-RUN npm install -g --ignore-scripts @anthropic-ai/claude-code@2.1.84 @playwright/cli@0.1.1
+RUN npm install -g --ignore-scripts @playwright/cli@0.1.1
 RUN mkdir -p /tmp/.claude/skills && \
     playwright-cli install --skills && \
     cp -r .claude/skills/playwright-cli /tmp/.claude/skills/ && \
@@ -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.
 
@@ -73,7 +77,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, Google Vertex AI, 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 +97,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 +112,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 +199,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, Google Vertex AI, 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 +217,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 +256,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/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,22 @@
 /**
  * `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 { fail } from '../errors.js';
 import { getWorkspacesDir } from '../home.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 +32,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 +53,125 @@ 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;
+    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(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;
+      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() ? `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,63 +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 fs from 'node:fs';
 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' | 'vertex';
+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: 'vertex' as const, label: 'Claude via Google Vertex AI' },
+      { 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 'vertex':
-      return setupVertex();
+    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> {
@@ -70,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> {
@@ -188,118 +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();
-
-  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();
-
-  const large = await p.text({
-    message: 'Large model ID',
-    placeholder: 'us.anthropic.claude-opus-4-8',
-    validate: required('Large model ID is required'),
-  });
-  if (p.isCancel(large)) return cancelAndExit();
-
-  return {
-    bedrock: { use: true, region, token },
-    models: { small, medium, large },
-  };
+  return { bedrock: { region, token } };
 }
 
-async function setupVertex(): Promise<ShannonConfig> {
-  // 1. Collect region and project ID
-  const region = await p.text({
-    message: 'Google Cloud region',
-    placeholder: 'us-east5',
-    validate: required('Region is required'),
-  });
-  if (p.isCancel(region)) return cancelAndExit();
+interface GatewaySetup {
+  provider: CuratedProviderId;
+  config: ShannonConfig;
+  baseUrl: string;
+  format?: OpenAiFormat;
+}
 
-  const projectId = await p.text({
-    message: 'GCP Project ID',
-    validate: required('Project 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(projectId)) return cancelAndExit();
+  if (p.isCancel(choice)) return cancelAndExit();
 
-  // 2. File picker for service account key
-  p.log.info('Select the path to your GCP Service Account JSON key file.');
-  const keySourcePath = await p.path({
-    message: 'Service Account JSON key file',
+  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 'Path is required';
-      if (!fs.existsSync(value)) return 'File not found';
-      if (!value.endsWith('.json')) return 'Must be a .json file';
+      if (!value) return 'Endpoint URL is required';
+      try {
+        new URL(value);
+      } catch {
+        return 'Must be a valid URL';
+      }
       return undefined;
     },
   });
-  if (p.isCancel(keySourcePath)) return cancelAndExit();
+  if (p.isCancel(baseUrl)) return cancelAndExit();
 
-  // 3. Copy key to ~/.shannon/ and lock permissions
-  const destPath = path.join(SHANNON_HOME, 'google-sa-key.json');
-  fs.mkdirSync(SHANNON_HOME, { recursive: true });
-  fs.copyFileSync(keySourcePath, destPath);
-  fs.chmodSync(destPath, 0o600);
-  p.log.success(`Key copied to ${destPath} (permissions: 0600)`);
+  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 }) } };
 
-  // 4. Model tiers
-  const models = await p.group({
-    small: () =>
-      p.text({
-        message: 'Small model ID',
-        placeholder: 'claude-haiku-4-5@20251001',
-        validate: required('Small model ID is required'),
-      }),
-    medium: () =>
-      p.text({
-        message: 'Medium model ID',
-        placeholder: 'claude-sonnet-4-6',
-        validate: required('Medium model ID is required'),
-      }),
-    large: () =>
-      p.text({
-        message: 'Large model ID',
-        placeholder: 'claude-opus-4-8',
-        validate: required('Large model ID is required'),
-      }),
+  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(models)) return cancelAndExit();
+  if (p.isCancel(choice)) return cancelAndExit();
 
-  return {
-    vertex: {
-      use: true,
-      region,
-      project_id: projectId,
-      key_path: destPath,
+  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;
     },
-    models: { small: models.small, medium: models.medium, large: models.large },
-  };
+  });
+  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,28 @@
 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 { getCredentialsPath, 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 { setTimeout as sleep } from 'node:timers/promises';
+import * as p from '@clack/prompts';
+import { ensureDocker, ensureImage, ensureInfra, randomSuffix, spawnWorker } from '../docker.js';
+import { buildEnvFlags, loadEnv, resolveHostPiAuthPath, shouldUsePiAuth, validateCredentials } from '../env.js';
+import { fail } from '../errors.js';
+import { getWorkspacesDir, initHome } from '../home.js';
+import { 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 +38,8 @@ export interface StartArgs {
   workspace?: string;
   output?: string;
   pipelineTesting: boolean;
-  debug: boolean;
+  keepContainer: boolean;
+  follow: boolean;
   version: string;
 }
 
@@ -58,22 +74,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();
@@ -107,15 +135,8 @@ export async function start(args: StartArgs): Promise<void> {
   }
   fs.mkdirSync(path.join(repo.hostPath, '.playwright'), { recursive: true });
 
-  const credentialsPath = getCredentialsPath();
-  const hasCredentials = fs.existsSync(credentialsPath);
-
-  if (hasCredentials) {
-    process.env.GOOGLE_APPLICATION_CREDENTIALS = '/app/credentials/google-sa-key.json';
-  }
-
   // 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 });
   }
@@ -123,10 +144,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,
@@ -136,24 +154,22 @@ export async function start(args: StartArgs): Promise<void> {
     containerName,
     envFlags: buildEnvFlags(),
     ...(config && { config }),
-    ...(hasCredentials && { credentials: credentialsPath }),
     ...(promptsDir && { promptsDir }),
     ...(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);
   }
 
@@ -170,64 +186,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);
@@ -237,9 +212,91 @@ 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}`);
@@ -247,51 +304,45 @@ function printDebugHint(containerName: string): void {
   console.log('');
 }
 
-function printInfo(
-  args: StartArgs,
-  workspace: string,
-  workflowId: string,
-  repoPath: string,
-  workspacesDir: string,
-): void {
-  const logsCmd = isLocal() ? `./shannon logs ${workspace}` : `npx @keygraph/shannon logs ${workspace}`;
-  const reportPath = path.join(workspacesDir, workspace, FINAL_REPORT_FILENAME);
+function printInfo(args: StartArgs, workspace: string, repoPath: string, workspacesDir: string): void {
+  const interactive = stdoutIsTerminal();
+
+  if (interactive && !args.follow) {
+    console.log('  It runs in the background — you can close this terminal.');
+    console.log('');
+  }
 
-  console.log('  Scan started — it runs in the background, so you can close this terminal.');
-  console.log('');
   console.log(`  Target:     ${args.url}`);
-  console.log(`  Repository: ${repoPath}`);
+  console.log(`  Repository: ${interactive ? repoPath : path.basename(repoPath)}`);
   console.log(`  Workspace:  ${workspace}`);
   if (args.config) {
-    console.log(`  Config:     ${path.resolve(args.config)}`);
+    console.log(`  Config:     ${interactive ? path.resolve(args.config) : path.basename(args.config)}`);
   }
   if (args.pipelineTesting) {
     console.log('  Mode:       Pipeline Testing');
   }
 
-  // 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(`  Model:      ${spec.providerId}:${spec.modelId}`);
   }
 
-  console.log('');
-  console.log('  Watch scan progress:');
-  console.log(`    Live logs:  ${logsCmd}`);
-  if (workflowId) {
-    console.log(`    Dashboard:  http://localhost:8233/namespaces/default/workflows/${workflowId}`);
-  } else {
-    console.log('    Dashboard:  http://localhost:8233');
+  if (!interactive) {
+    return;
   }
+
+  const reportPath = path.join(workspacesDir, workspace, FINAL_REPORT_PDF_FILENAME);
+
+  // When following, the scan log streams inline next, so the "run these to watch it" hints
+  // would only contradict that.
+  if (!args.follow) {
+    const prefix = commandPrefix();
+    console.log('');
+    console.log('  Watch scan progress:');
+    console.log(`    Live logs:  ${prefix} logs ${workspace}`);
+    console.log(`    Progress:   ${prefix} status ${workspace}`);
+  }
+
   console.log('');
   console.log('  Report (when the scan finishes):');
   console.log(`    ${reportPath}`);

apps/cli/src/commands/status.ts

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

apps/cli/src/commands/stop.ts

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

apps/cli/src/commands/uninstall.ts

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

apps/cli/src/commands/workspaces.ts

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

apps/cli/src/config/resolver.ts

@@ -7,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,35 +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_CODE_MAX_OUTPUT_TOKENS', toml: 'core.max_tokens', type: 'number' },
-  { 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' },
 
-  // Vertex
-  { env: 'CLAUDE_CODE_USE_VERTEX', toml: 'vertex.use', type: 'boolean' },
-  { env: 'CLOUD_ML_REGION', toml: 'vertex.region', type: 'string' },
-  { env: 'ANTHROPIC_VERTEX_PROJECT_ID', toml: 'vertex.project_id', type: 'string' },
-  { env: 'GOOGLE_APPLICATION_CREDENTIALS', toml: 'vertex.key_path', 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;
@@ -88,10 +101,9 @@ function loadTOML(): TOMLConfig | null {
     const mode = fs.statSync(configPath).mode;
     if (mode & 0o077) {
       const actual = (mode & 0o777).toString(8).padStart(3, '0');
-      console.error(
-        `\nYour config file is readable by other users on this machine (${actual}). Lock it down: chmod 600 ${configPath}\n`,
+      fail(
+        `Your config file is readable by other users on this machine (${actual}). Lock it down: chmod 600 ${configPath}`,
       );
-      process.exit(1);
     }
   }
 
@@ -100,9 +112,7 @@ function loadTOML(): TOMLConfig | null {
     return parseTOML(content) as TOMLConfig;
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`\nFailed to parse ${configPath}: ${message}`);
-    console.error(`\nRun 'npx @keygraph/shannon setup' to reconfigure.\n`);
-    process.exit(1);
+    fail(`Failed to parse ${configPath}: ${message}`, `Run 'npx @keygraph/shannon setup' to reconfigure.`);
   }
 }
 
@@ -125,62 +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;
-    }
-
-    case 'vertex': {
-      const required = ['use', 'region', 'project_id', 'key_path'];
-      const missing = required.filter((k) => !keys.includes(k));
-      if (missing.length > 0) {
-        errors.push(`[vertex] missing required keys: ${missing.join(', ')}`);
-      }
-      validateModelTiers(config, 'vertex', errors);
-      break;
-    }
-  }
-}
-
-/** Bedrock and Vertex require 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`);
   }
 }
 
@@ -228,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', 'vertex'] 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;
 }
@@ -268,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,12 +8,13 @@ import { getConfigFile } from '../home.js';
 // === Types ===
 
 export interface ShannonConfig {
-  core?: { max_tokens?: number; 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 };
-  vertex?: { use?: boolean; region?: string; project_id?: string; key_path?: 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;
@@ -237,25 +291,28 @@ export interface WorkerOptions {
   containerName: string;
   envFlags: string[];
   config?: { hostPath: string; containerPath: string };
-  credentials?: string;
   promptsDir?: string;
   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());
 
@@ -293,9 +350,9 @@ export function spawnWorker(opts: WorkerOptions): ChildProcess {
     args.push('-v', `${opts.outputDir}:/app/output`);
   }
 
-  // Mount credentials file to fixed container path
-  if (opts.credentials) {
-    args.push('-v', `${opts.credentials}:/app/credentials/google-sa-key.json:ro`);
+  // 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
@@ -330,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.`);
+  }
 }
 
 /**
@@ -365,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,30 +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',
-  'CLAUDE_CODE_USE_VERTEX',
-  'CLOUD_ML_REGION',
-  'ANTHROPIC_VERTEX_PROJECT_ID',
-  'GOOGLE_APPLICATION_CREDENTIALS',
-  'ANTHROPIC_SMALL_MODEL',
-  'ANTHROPIC_MEDIUM_MODEL',
-  'ANTHROPIC_LARGE_MODEL',
-  'CLAUDE_CODE_MAX_OUTPUT_TOKENS',
-  '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.
@@ -44,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);
     }
   }
 
@@ -62,95 +109,91 @@ export function buildEnvFlags(): string[] {
 interface CredentialValidation {
   valid: boolean;
   error?: string;
-  mode: 'api-key' | 'oauth' | 'custom-base-url' | 'bedrock' | 'vertex';
 }
 
-/** 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');
-  if (process.env.CLAUDE_CODE_USE_VERTEX === '1') providers.push('Google Vertex');
-  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' };
-  }
-  if (process.env.CLAUDE_CODE_USE_VERTEX === '1') {
-    const missing: string[] = [];
-    if (!process.env.CLOUD_ML_REGION) missing.push('CLOUD_ML_REGION');
-    if (!process.env.ANTHROPIC_VERTEX_PROJECT_ID) missing.push('ANTHROPIC_VERTEX_PROJECT_ID');
-    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: 'vertex',
-        error: `Vertex AI mode requires: ${missing.join(', ')}`,
-      };
-    }
-    if (!process.env.GOOGLE_APPLICATION_CREDENTIALS) {
-      return {
-        valid: false,
-        mode: 'vertex',
-        error: 'Vertex AI mode requires GOOGLE_APPLICATION_CREDENTIALS',
-      };
-    }
-    return { valid: true, mode: 'vertex' };
+    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/home.ts

@@ -1,7 +1,7 @@
 /**
  * Shannon state directory management.
  *
- * Local mode (cloned repo): uses ./workspaces/, ./credentials/
+ * Local mode (cloned repo): uses ./workspaces/
  * NPX mode: uses ~/.shannon/workspaces/, ~/.shannon/
  */
 
@@ -20,32 +20,14 @@ export function getWorkspacesDir(): string {
   return getMode() === 'local' ? path.resolve('workspaces') : path.join(SHANNON_HOME, 'workspaces');
 }
 
-/**
- * Resolve the Vertex credentials file path.
- *
- * Checks GOOGLE_APPLICATION_CREDENTIALS env var first (may be set by TOML resolver),
- * then falls back to mode-appropriate default location.
- */
-export function getCredentialsPath(): string {
-  const envPath = process.env.GOOGLE_APPLICATION_CREDENTIALS;
-  if (envPath && fs.existsSync(envPath)) return path.resolve(envPath);
-
-  if (getMode() === 'local') {
-    return path.resolve('credentials', 'google-sa-key.json');
-  }
-
-  return path.join(SHANNON_HOME, 'google-sa-key.json');
-}
-
 /**
  * Initialize state directories.
- * Local mode: creates ./workspaces/ and ./credentials/
+ * Local mode: creates ./workspaces/
  * NPX mode: creates ~/.shannon/workspaces/
  */
 export function initHome(): void {
   if (getMode() === 'local') {
     fs.mkdirSync(path.resolve('workspaces'), { recursive: true });
-    fs.mkdirSync(path.resolve('credentials'), { recursive: true });
   } else {
     fs.mkdirSync(path.join(SHANNON_HOME, 'workspaces'), { recursive: true });
   }

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/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

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

apps/worker/prompts/exploit-auth.txt

@@ -116,7 +116,7 @@ Before beginning exploitation, read these strategic intelligence files in order:
 2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, user roles, and data flow maps.
 3.  `.shannon/deliverables/auth_analysis_deliverable.md` - Strategic context from the Auth analysis specialist, including notes on session mechanisms, password policies, and flawed logic paths.
 
-- You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
+- You will manage your work using the **`todo_write` tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
 
 <system_architecture>
@@ -145,18 +145,18 @@ You are the **Identity Compromise Specialist** - proving tangible impact of brok
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Essential for interacting with multi-step authentication flows, injecting stolen session cookies, and verifying account takeover in a real browser context. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
-- **Task Agent:** Mandatory coder-executor for brute force batches, credential stuffing, token replay automation, and any scripted workflow.
-- **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
-- **Read tool:** To read false positives from your tracking file at `workspace/auth_false_positives.md`.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent:** Mandatory coder-executor for brute force batches, credential stuffing, token replay automation, and any scripted workflow.
+- **`todo_write` tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
+- **`read` tool:** To read false positives from your tracking file at `workspace/auth_false_positives.md`.
 
 **CRITICAL TASK AGENT WORKFLOW:**
-- Delegate every custom script or multi-step automation to the Task Agent; do not hand-write scripts in Bash.
-- Keep requests ≤15 lines and use the template below so the Task Agent has clear inputs and success criteria.
+- Delegate every custom script or multi-step automation to the `task` agent; do not hand-write scripts in Bash.
+- Keep requests ≤15 lines and use the template below so the `task` agent has clear inputs and success criteria.
 </cli_tools>
 
-## Task Agent Scripting Requirements
-Use the Task Agent to execute all bulk or repetitive auth attacks. Manual commands are for quick verification only.
+## `task` agent Scripting Requirements
+Use the `task` agent to execute all bulk or repetitive auth attacks. Manual commands are for quick verification only.
 
 **MANDATORY TEMPLATE:**
 "
@@ -172,7 +172,7 @@ Inputs:
 Success Criteria: Print each attempt with status code and key response text so I can evaluate impact.
 "
 
-**DO NOT:** exceed 5–6 inputs per run, ask for advanced parsing, or bypass the Task Agent for scripting.
+**DO NOT:** exceed 5–6 inputs per run, ask for advanced parsing, or bypass the `task` agent for scripting.
 
 <methodology_and_domain_expertise>
 
@@ -183,11 +183,11 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 - **Complete the Workflow:** For each vulnerability, you must follow the full Exploitation Workflow from Confirmation to Impact Demonstration.
 
 ## **The Task-Based Attack Plan**
-Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
+Your entire exploitation process will be managed through the `todo_write` tool. You MUST adhere to this process.
 
 **1. Initialization:**
 - Read `.shannon/deliverables/auth_exploitation_queue.json`.
-- Use the TodoWrite tool to create tasks for each vulnerability in the queue.
+- Use the `todo_write` tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
     - "AUTH-VULN-01: Exploit Session Fixation on /login (Hypothesis: Session ID not rotated)"
@@ -195,10 +195,10 @@ Your entire exploitation process will be managed through the TodoWrite tool. You
 
 **2. The Execution Loop:**
 - **A. Get Next Task:** Review your todo list and identify the next pending task to work on.
-- **B. Plan & Decompose:** Mark the task as in_progress using TodoWrite. Read the `suggested_exploit_technique` from the vulnerability details. This is your primary directive. Plan the specific commands and tools needed to execute this attack pattern. If the attack is complex (e.g., a multi-step logic flaw), use TodoWrite to add smaller tasks.
+- **B. Plan & Decompose:** Mark the task as in_progress using `todo_write`. Read the `suggested_exploit_technique` from the vulnerability details. This is your primary directive. Plan the specific commands and tools needed to execute this attack pattern. If the attack is complex (e.g., a multi-step logic flaw), use `todo_write` to add smaller tasks.
 - **C. Execute:** Run the command for the current task.
-- **D. Update & Document:** Based on the result, update the TodoWrite status to completed if successful. Document the outcome in your memory for the final report.
-- **E. Expand the Plan (Branching):** If successful and more steps are needed, use TodoWrite to add the next logical tasks required by the OWASP workflow.
+- **D. Update & Document:** Based on the result, update the `todo_write` status to completed if successful. Document the outcome in your memory for the final report.
+- **E. Expand the Plan (Branching):** If successful and more steps are needed, use `todo_write` to add the next logical tasks required by the OWASP workflow.
 
 ## **OWASP Authentication Exploitation Workflow**
 For each root vulnerability, follow this systematic, two-stage attack flow.
@@ -289,7 +289,7 @@ Prioritize these based on the intelligence from your queue and vulnerability ana
 **2. Credential-Based Attacks**
 - **Credential Stuffing with cURL:**
   `curl -X POST -H "Content-Type: application/json" -d '{"username":"admin", "password":"CrackedPassword123"}' https://target.com/api/login`
-- **Brute Force (Example with Task Agent):**
+- **Brute Force (Example with `task` agent):**
   "Task: Write a python script to POST to /api/login with username 'admin' and passwords from this list: ['admin', 'password', '123456']. Print the status code for each."
 
 **3. Logic Flaws**
@@ -304,8 +304,8 @@ Prioritize these based on the intelligence from your queue and vulnerability ana
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/auth_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
+<deliverable_tools>
+You emit your exploitation evidence through a single tool — `add_exploit`. The host renderer assembles `.shannon/deliverables/auth_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
 **When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
@@ -316,7 +316,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 **Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
 **Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -328,7 +328,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 - All technical components specified without ambiguity
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
-	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
+	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the `todo_write` tool.
 	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/auth_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/auth_false_positives.md`, not via `add_exploit`.
 
 CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/auth_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.

apps/worker/prompts/exploit-authz.txt

@@ -105,7 +105,7 @@ Before beginning exploitation, read these strategic intelligence files in order:
 2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, user roles, and permission models.
 3.  `.shannon/deliverables/authz_analysis_deliverable.md` - Strategic context from the Authz analysis specialist, including notes on access control patterns, role hierarchies, and flawed logic paths.
 
-- You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
+- You will manage your work using the **`todo_write` tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
 
 <system_architecture>
@@ -134,18 +134,18 @@ You are the **Privilege Escalation Specialist** - proving tangible impact of bro
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Essential for interacting with complex authorization flows, testing role-based access controls in browser contexts, and verifying privilege escalation through UI elements. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
-- **Task Agent:** Mandatory coder-executor for IDOR sweeps, role escalation loops, and workflow bypass automation.
-- **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
-- **Read tool:** To read false positives from your tracking file at `workspace/authz_false_positives.md`.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent:** Mandatory coder-executor for IDOR sweeps, role escalation loops, and workflow bypass automation.
+- **`todo_write` tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
+- **`read` tool:** To read false positives from your tracking file at `workspace/authz_false_positives.md`.
 
 **CRITICAL TASK AGENT WORKFLOW:**
-- Delegate every multi-user iteration, role toggle test, or workflow automation script to the Task Agent—never handcraft these scripts yourself.
-- Keep requests ≤15 lines and adhere to the template below so the Task Agent can act deterministically.
+- Delegate every multi-user iteration, role toggle test, or workflow automation script to the `task` agent—never handcraft these scripts yourself.
+- Keep requests ≤15 lines and adhere to the template below so the `task` agent can act deterministically.
 </cli_tools>
 
-## Task Agent Scripting Requirements
-All repeated authorization tests must run through the Task Agent.
+## `task` agent Scripting Requirements
+All repeated authorization tests must run through the `task` agent.
 
 **MANDATORY TEMPLATE:**
 "
@@ -161,7 +161,7 @@ Inputs:
 Success Criteria: Execute one request per identity, logging status code and key response text so I can confirm access levels.
 "
 
-**DO NOT:** exceed 5 identities per run, ask for complex diffing, or bypass the Task Agent for scripting.
+**DO NOT:** exceed 5 identities per run, ask for complex diffing, or bypass the `task` agent for scripting.
 
 <methodology_and_domain_expertise>
 
@@ -172,11 +172,11 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 - **Complete the Workflow:** For each vulnerability, you must follow the full Exploitation Workflow from Confirmation to Impact Demonstration.
 
 ## **The Task-Based Attack Plan**
-Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
+Your entire exploitation process will be managed through the `todo_write` tool. You MUST adhere to this process.
 
 **1. Initialization:**
 - Read `.shannon/deliverables/authz_exploitation_queue.json`.
-- Use the TodoWrite tool to create tasks for each vulnerability in the queue.
+- Use the `todo_write` tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID, type, and the hypothesis to test.
     Example tasks:
     - "AUTHZ-VULN-01 (Horizontal): Exploit ownership bypass on /api/user/{id} (Hypothesis: Access to other users' data)"
@@ -185,10 +185,10 @@ Your entire exploitation process will be managed through the TodoWrite tool. You
 
 **2. The Execution Loop:**
 - **A. Get Next Task:** Review your todo list and identify the next pending task to work on.
-- **B. Plan & Decompose:** Mark the task as in_progress using TodoWrite. Read the vulnerability type (`Horizontal`, `Vertical`, or `Context_Workflow`) and the `minimal_witness` from the vulnerability details. This is your primary directive. Plan the specific commands and tools needed to execute this attack pattern. If the attack is complex (e.g., a multi-step privilege escalation), use TodoWrite to add smaller tasks.
+- **B. Plan & Decompose:** Mark the task as in_progress using `todo_write`. Read the vulnerability type (`Horizontal`, `Vertical`, or `Context_Workflow`) and the `minimal_witness` from the vulnerability details. This is your primary directive. Plan the specific commands and tools needed to execute this attack pattern. If the attack is complex (e.g., a multi-step privilege escalation), use `todo_write` to add smaller tasks.
 - **C. Execute:** Run the command for the current task.
-- **D. Update & Document:** Based on the result, update the TodoWrite status to completed if successful. Document the outcome in your memory for the final report.
-- **E. Expand the Plan (Branching):** If successful and more steps are needed, use TodoWrite to add the next logical tasks required by the OWASP workflow.
+- **D. Update & Document:** Based on the result, update the `todo_write` status to completed if successful. Document the outcome in your memory for the final report.
+- **E. Expand the Plan (Branching):** If successful and more steps are needed, use `todo_write` to add the next logical tasks required by the OWASP workflow.
 
 ## **OWASP Authorization Exploitation Workflow**
 For each root vulnerability, follow this systematic, two-stage attack flow.
@@ -312,8 +312,8 @@ Remember: The most effective attacks often come from understanding the specific
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/authz_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
+<deliverable_tools>
+You emit your exploitation evidence through a single tool — `add_exploit`. The host renderer assembles `.shannon/deliverables/authz_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
 **When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
@@ -324,7 +324,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 **Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
 **Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -336,7 +336,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 - All technical components specified without ambiguity
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
-	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
+	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the `todo_write` tool.
 	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/authz_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/authz_false_positives.md`, not via `add_exploit`.
 
 CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/authz_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.

apps/worker/prompts/exploit-injection.txt

@@ -87,7 +87,7 @@ Before beginning exploitation, read these strategic intelligence files in order:
 - Leverage vulnerability details and context from pre-analysis rather than blind testing.
 - Reference provided vulnerable code snippets to avoid blind guessing of query column counts, command syntax, or database/OS types.
 
-- You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
+- You will manage your work using the **`todo_write` tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
 
 <system_architecture>
@@ -116,13 +116,13 @@ You are the **Proof-of-Impact Generator** - converting theoretical injection fla
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** For testing injection vulnerabilities through browser interactions when needed. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
-- **Task Agent:** Mandatory coder-executor for any custom scripting beyond single ad-hoc commands.
-- **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
-- **Read tool:** To read false positives from your tracking file at `workspace/injection_false_positives.md`.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent:** Mandatory coder-executor for any custom scripting beyond single ad-hoc commands.
+- **`todo_write` tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
+- **`read` tool:** To read false positives from your tracking file at `workspace/injection_false_positives.md`.
 
 **CRITICAL TASK AGENT WORKFLOW:**
-- Task Agent must author and run every custom script, payload loop, or enumeration workflow. Do not craft standalone scripts in Bash or other tools.
+- `task` agent must author and run every custom script, payload loop, or enumeration workflow. Do not craft standalone scripts in Bash or other tools.
 - Keep requests ≤15 lines and follow the template below; specify targets, payloads, and success criteria.
 </cli_tools>
 
@@ -135,11 +135,11 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 - **Complete the Workflow:** For each vulnerability, you must follow the full OWASP Exploitation Workflow from Confirmation to either Exfiltration or a documented conclusion of non-exploitability.
 
 ## **The Task-Based Attack Plan**
-Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
+Your entire exploitation process will be managed through the `todo_write` tool. You MUST adhere to this process.
 
 **1. Initialization:**
 - Read the `.shannon/deliverables/injection_exploitation_queue.json` file.
-- Use the TodoWrite tool to create tasks for each vulnerability in the queue.
+- Use the `todo_write` tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
     - "SQLI-VULN-01: Exploit endpoint /api/search?q= (Hypothesis: Basic UNION injection)"
@@ -150,16 +150,16 @@ You will repeatedly perform the following loop until all tasks are completed:
 
 - **A. Get Next Task:** Review your todo list and identify the next pending task to work on.
 
-- **B. Plan & Decompose:** Mark the task as in_progress using TodoWrite. Decide on the concrete command or action. If the task is complex (e.g., "Enumerate tables"), use TodoWrite to add smaller, actionable tasks.
+- **B. Plan & Decompose:** Mark the task as in_progress using `todo_write`. Decide on the concrete command or action. If the task is complex (e.g., "Enumerate tables"), use `todo_write` to add smaller, actionable tasks.
 
 - **C. Execute:** Run the command for the current task (e.g., run `curl` with an `ORDER BY` payload).
 
-- **D. Update & Document:** Based on the result, update the TodoWrite status:
+- **D. Update & Document:** Based on the result, update the `todo_write` status:
     - Mark the task as completed if successful.
     - Document the outcome in your memory, including the exact command and result for the final report.
     - Example outcome to remember: "Step 1.1: Determined column count is 4 using ORDER BY - Command: curl 'https://target.com/api/search?q=test' ORDER BY 4--'"
 
-- **E. Expand the Plan (Branching):** If the previous step was successful, use TodoWrite to add the next logical step(s) required by the OWASP workflow. **You must complete all required tasks for a vulnerability.** You are not permitted to skip tasks.
+- **E. Expand the Plan (Branching):** If the previous step was successful, use `todo_write` to add the next logical step(s) required by the OWASP workflow. **You must complete all required tasks for a vulnerability.** You are not permitted to skip tasks.
 
 ## **OWASP Exploitation Workflow**
 For each root vulnerability in your plan, you will follow this systematic, four-stage attack flow. These stages will become the structured steps in your Markdown plan.
@@ -184,11 +184,11 @@ Use the right tool for the job to ensure thoroughness.
 Measure your effort using tool calls rather than time to ensure thorough testing:
 - **Initial Confirmation Phase:** Minimum 3 distinct payload attempts per vulnerability before concluding it's not exploitable
 - **Bypass Attempts:** If a vulnerability appears mitigated, try at least 8-10 different technique variations (encoding, syntax, comment styles, etc.) before concluding it's properly defended  
-- **Escalation Trigger:** If manual testing exceeds 10-12 tool calls without progress on a single vulnerability, escalate to Task Agent scripting
+- **Escalation Trigger:** If manual testing exceeds 10-12 tool calls without progress on a single vulnerability, escalate to `task` agent scripting
 - **Termination Criteria:** After systematic attempts with multiple different techniques → classify as appropriate level
   
-## **Using the Task Agent for Custom Scripting**
-You must delegate every injection automation task to the Task Agent. Use manual `curl` runs for spot checks, then escalate to scripted payload loops handled by the Task Agent.
+## **Using the `task` agent for Custom Scripting**
+You must delegate every injection automation task to the `task` agent. Use manual `curl` runs for spot checks, then escalate to scripted payload loops handled by the `task` agent.
 
 **TEMPLATE FOR SCRIPTING TASKS (REQUIRED):**
 "
@@ -204,7 +204,7 @@ Inputs:
 Success Criteria: Print status code and response excerpt for each payload so I can analyze impact.
 "
 
-**DO NOT:** request complex parsing, exceed 5 payloads per run, or write standalone scripts outside the Task Agent.
+**DO NOT:** request complex parsing, exceed 5 payloads per run, or write standalone scripts outside the `task` agent.
 
 ### Proof of Exploitation Levels
 
@@ -335,8 +335,8 @@ Prioritize your techniques based on the intelligence from the analysis deliverab
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/injection_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
+<deliverable_tools>
+You emit your exploitation evidence through a single tool — `add_exploit`. The host renderer assembles `.shannon/deliverables/injection_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
 **When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
@@ -347,7 +347,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 **Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
 **Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -359,7 +359,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 - All technical components specified without ambiguity
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
-1.  **Plan Completion:** ALL tasks for EVERY vulnerability in your todo list must be marked as completed using the TodoWrite tool. **No vulnerability or task can be left unaddressed.**
+1.  **Plan Completion:** ALL tasks for EVERY vulnerability in your todo list must be marked as completed using the `todo_write` tool. **No vulnerability or task can be left unaddressed.**
 2.  **Evidence Emission:** Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/injection_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/injection_false_positives.md`, not via `add_exploit`.
 
 **CRITICAL WARNING:** Announcing completion before every item in `.shannon/deliverables/injection_exploitation_queue.json` has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure. Superficial testing is not acceptable.

apps/worker/prompts/exploit-ssrf.txt

@@ -105,7 +105,7 @@ Before beginning exploitation, read these strategic intelligence files in order:
 2.  `.shannon/deliverables/recon_deliverable.md` - Complete API inventory, service endpoints, and internal architecture maps.
 3.  `.shannon/deliverables/ssrf_analysis_deliverable.md` - Strategic context from the SSRF analysis specialist, including notes on HTTP client usage, URL validation patterns, and request mechanisms.
 
-- You will manage your work using the **TodoWrite tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
+- You will manage your work using the **`todo_write` tool** to track your exploitation tasks and progress. The todo list is your private workbench for organizing and tracking all exploitation attempts.
 </starting_context>
 
 <system_architecture>
@@ -133,19 +133,19 @@ You are the **Network Boundary Breaker** - proving tangible impact of SSRF vulne
 </system_architecture>
 
 <cli_tools>
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** Useful for complex multi-step SSRF exploitation that requires browser context or JavaScript execution. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Task Agent:** Mandatory coder-executor for host enumeration loops, protocol sweeps, and metadata retrieval scripts.
-- **TodoWrite tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
-- **Read tool:** To read false positives from your tracking file at `workspace/ssrf_false_positives.md`.
+- **`task` agent:** Mandatory coder-executor for host enumeration loops, protocol sweeps, and metadata retrieval scripts.
+- **`todo_write` tool:** Essential for managing your exploitation task list. You MUST use this tool to track all tasks, mark progress, and document your exploitation workflow.
+- **`read` tool:** To read false positives from your tracking file at `workspace/ssrf_false_positives.md`.
 
 **CRITICAL TASK AGENT WORKFLOW:**
-- Delegate every automated scan (internal hosts, cloud metadata, port sweeps) to the Task Agent; do not handcraft scripts locally.
+- Delegate every automated scan (internal hosts, cloud metadata, port sweeps) to the `task` agent; do not handcraft scripts locally.
 - Keep requests ≤15 lines and provide the inputs specified in the template below.
 </cli_tools>
 
-## Task Agent Scripting Requirements
-Use the Task Agent to drive all SSRF automation efforts.
+## `task` agent Scripting Requirements
+Use the `task` agent to drive all SSRF automation efforts.
 
 **MANDATORY TEMPLATE:**
 "
@@ -161,7 +161,7 @@ Inputs:
 Success Criteria: Issue requests for each target, log status code and indicator snippet so I can confirm impact.
 "
 
-**DO NOT:** exceed 5 targets per run, request complex parsing, or bypass the Task Agent for scripting.
+**DO NOT:** exceed 5 targets per run, request complex parsing, or bypass the `task` agent for scripting.
 
 <methodology_and_domain_expertise>
 
@@ -172,11 +172,11 @@ Your primary goal is to achieve a definitive, evidence-backed conclusion for **e
 - **Complete the Workflow:** For each vulnerability, you must follow the full Exploitation Workflow from Confirmation to Impact Demonstration.
 
 ## **The Task-Based Attack Plan**
-Your entire exploitation process will be managed through the TodoWrite tool. You MUST adhere to this process.
+Your entire exploitation process will be managed through the `todo_write` tool. You MUST adhere to this process.
 
 **1. Initialization:**
 - Read `.shannon/deliverables/ssrf_exploitation_queue.json`.
-- Use the TodoWrite tool to create tasks for each vulnerability in the queue.
+- Use the `todo_write` tool to create tasks for each vulnerability in the queue.
 - Each task should include the vulnerability ID and the hypothesis to test.
     Example tasks:
     - "SSRF-VULN-01: Exploit URL manipulation on /api/fetch (Hypothesis: Internal service access)"
@@ -184,10 +184,10 @@ Your entire exploitation process will be managed through the TodoWrite tool. You
 
 **2. The Execution Loop:**
 - **A. Get Next Task:** Review your todo list and identify the next pending task to work on.
-- **B. Plan & Decompose:** Mark the task as in_progress using TodoWrite. Read the `suggested_exploit_technique` from the vulnerability details. This is your primary directive. Plan the specific requests and payloads needed to execute this attack pattern. If the attack is complex (e.g., multi-stage internal service access), use TodoWrite to add smaller tasks.
+- **B. Plan & Decompose:** Mark the task as in_progress using `todo_write`. Read the `suggested_exploit_technique` from the vulnerability details. This is your primary directive. Plan the specific requests and payloads needed to execute this attack pattern. If the attack is complex (e.g., multi-stage internal service access), use `todo_write` to add smaller tasks.
 - **C. Execute:** Run the command for the current task.
-- **D. Update & Document:** Based on the result, update the TodoWrite status to completed if successful. Document the outcome in your memory for the final report.
-- **E. Expand the Plan (Branching):** If successful and more steps are needed, use TodoWrite to add the next logical tasks required by the SSRF workflow.
+- **D. Update & Document:** Based on the result, update the `todo_write` status to completed if successful. Document the outcome in your memory for the final report.
+- **E. Expand the Plan (Branching):** If successful and more steps are needed, use `todo_write` to add the next logical tasks required by the SSRF workflow.
 
 ## **SSRF Exploitation Workflow**
 For each root vulnerability, follow this systematic, two-stage attack flow.
@@ -389,8 +389,8 @@ A successful SSRF doesn't always mean data is immediately exfiltrated. Validatio
 </attack_patterns>
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/ssrf_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
+<deliverable_tools>
+You emit your exploitation evidence through a single tool — `add_exploit`. The host renderer assembles `.shannon/deliverables/ssrf_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
 **When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
@@ -401,7 +401,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 **Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
 **Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification
@@ -413,7 +413,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 - All technical components specified without ambiguity
 
 COMPLETION REQUIREMENTS (ALL must be satisfied):
-	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the TodoWrite tool.
+	1. Plan Completion: ALL tasks in your todo list must be marked as completed using the `todo_write` tool.
 	2. Evidence Emission: Every non-FALSE-POSITIVE vulnerability in `.shannon/deliverables/ssrf_exploitation_queue.json` has been recorded with one `add_exploit` call carrying the appropriate `status` ("exploited" or "blocked") and required fields. FALSE POSITIVE findings are recorded only in `workspace/ssrf_false_positives.md`, not via `add_exploit`.
 
 CRITICAL WARNING: Announcing completion before every item in .shannon/deliverables/ssrf_exploitation_queue.json has been pursued to a final, evidence-backed conclusion (either successfully exploited, recorded as potential-but-blocked, or verified false positive) will be considered a mission failure.

apps/worker/prompts/exploit-xss.txt

@@ -107,7 +107,7 @@ Before beginning exploitation, read these strategic intelligence files in order:
 - Use the `render_context` and `mismatch_reason` from the analysis queue to craft precise initial payloads.
 - Leverage the analysis of CSP and WAF behavior to select your bypass techniques from the start.
 
-- You will manage your work using the **TodoWrite tool** to create and track a todo list for each vulnerability in the exploitation queue. This provides structured tracking of your exploitation attempts.
+- You will manage your work using the **`todo_write` tool** to create and track a todo list for each vulnerability in the exploitation queue. This provides structured tracking of your exploitation attempts.
 </starting_context>
 
 <system_architecture>
@@ -136,18 +136,18 @@ You are the **Client-Side Impact Demonstrator** - converting theoretical XSS fla
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Your primary tool for testing DOM-based and Stored XSS, confirming script execution in a real browser context, and interacting with the application post-exploitation. Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
-- **Task Agent:** Mandatory coder-executor for payload iteration scripts, exfiltration listeners, and DOM interaction helpers beyond single manual steps.
-- **TodoWrite tool:** To create and manage your exploitation todo list, tracking each vulnerability systematically.
-- **Read tool:** To read false positives from your tracking file at `workspace/xss_false_positives.md`.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent:** Mandatory coder-executor for payload iteration scripts, exfiltration listeners, and DOM interaction helpers beyond single manual steps.
+- **`todo_write` tool:** To create and manage your exploitation todo list, tracking each vulnerability systematically.
+- **`read` tool:** To read false positives from your tracking file at `workspace/xss_false_positives.md`.
 
 **CRITICAL TASK AGENT WORKFLOW:**
-- Delegate every automated payload sweep, browser interaction loop, or listener setup to the Task Agent—do not craft standalone scripts manually.
+- Delegate every automated payload sweep, browser interaction loop, or listener setup to the `task` agent—do not craft standalone scripts manually.
 - Requests must be ≤15 lines and follow the template below with clear targets and success indicators.
 </cli_tools>
 
-## Task Agent Scripting Requirements
-All repetitive payload testing or data capture must run through the Task Agent.
+## `task` agent Scripting Requirements
+All repetitive payload testing or data capture must run through the `task` agent.
 
 **MANDATORY TEMPLATE:**
 "
@@ -163,7 +163,7 @@ Inputs:
 Success Criteria: Run each payload, log the indicator, and surface any captured data for my review.
 "
 
-**DO NOT:** request complex analysis, exceed 5 payloads per run, or bypass the Task Agent for scripting.
+**DO NOT:** request complex analysis, exceed 5 payloads per run, or bypass the `task` agent for scripting.
 
 <methodology_and_domain_expertise>
 
@@ -183,7 +183,7 @@ For **every single vulnerability** in your queue, systematically work through th
 
 **Actions:**
 - Read `.shannon/deliverables/xss_exploitation_queue.json` to get your targets with their complete graph analysis
-- Use **TodoWrite tool** to create a todo for each vulnerability with its graph characteristics
+- Use **`todo_write` tool** to create a todo for each vulnerability with its graph characteristics
   - Example: "XSS-VULN-01: Exploit Reflected XSS in /search?q= (source: URL param → no sanitization → innerHTML sink)"
 - Study the provided intelligence for each vulnerability:
   - `source_detail`: The exact entry point for your payload
@@ -322,8 +322,8 @@ POTENTIAL (Report in separate subsection):
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-You emit your exploitation evidence through a single MCP tool — `add_exploit` from the `exploit-collector` server. The host renderer assembles `.shannon/deliverables/xss_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
+<deliverable_tools>
+You emit your exploitation evidence through a single tool — `add_exploit`. The host renderer assembles `.shannon/deliverables/xss_exploitation_evidence.md` from your tool calls after the run. You do NOT write the Markdown file directly.
 
 **When to emit.** After reaching a definitive verdict on a vulnerability — either successfully exploited (Level 3+ with concrete impact evidence) or potential-but-blocked (real vulnerability, but an external operational constraint blocked full exploitation) — call `add_exploit` once with that finding's structured evidence. Call once per queue vulnerability; do not batch. Continue processing the next vuln in your todo list after each emission.
 
@@ -334,7 +334,7 @@ You emit your exploitation evidence through a single MCP tool — `add_exploit`
 **Idempotency.** Duplicate `vulnerability_id` calls are rejected with `DuplicateError`. Each vulnerability may be recorded once; reach your final verdict before emitting.
 
 **Required-call intent.** Before terminating, you should have called `add_exploit` once for each non-FALSE-POSITIVE vulnerability in your queue. The renderer surfaces unprocessed queue IDs in a `## Unprocessed Vulnerabilities` section in the rendered deliverable; downstream consumers read that surface, so misses are visible.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 ### Evidence Completeness Verification

apps/worker/prompts/pre-recon-code.txt

@@ -21,7 +21,7 @@ Filesystem:
 - Focus on SECURITY IMPLICATIONS and ACTIONABLE FINDINGS rather than just component listings
 - Identify trust boundaries, privilege escalation paths, and data flow security concerns
 - Include specific examples from the code when discussing security concerns
-- **MANDATORY:** You MUST emit your complete analysis by calling all seven `set_*` MCP tools listed in `<mcp_tools>` before terminating. The host renders the deliverable Markdown from those calls.
+- **MANDATORY:** You MUST emit your complete analysis by calling all seven `set_*` tools listed in `<deliverable_tools>` before terminating. The host renders the deliverable Markdown from those calls.
 
 **GIT AWARENESS:**
 Read `.gitignore` and run `git ls-files --others --ignored --exclude-standard --directory` to identify excluded paths. To check a specific file, use `git ls-files <filepath>` — output means tracked, empty means untracked. Only flag tracked files as vulnerabilities. Untracked files relevant to security (e.g., secrets, credentials, sensitive configs) may be noted as informational.
@@ -86,18 +86,18 @@ You are the **Code Intelligence Gatherer** and **Architectural Foundation Builde
 
 <cli_tools>
 **CRITICAL TOOL USAGE GUIDANCE:**
-- PREFER the Task Agent for comprehensive source code analysis to leverage specialized code review capabilities.
-- Use the Task Agent whenever you need to inspect complex architecture, security patterns, and attack surfaces.
-- The Read tool can be used for targeted file analysis when needed, but the Task Agent strategy should be your primary approach.
+- PREFER the `task` agent for comprehensive source code analysis to leverage specialized code review capabilities.
+- Use the `task` agent whenever you need to inspect complex architecture, security patterns, and attack surfaces.
+- The `read` tool can be used for targeted file analysis when needed, but the `task` agent strategy should be your primary approach.
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication mechanisms, map attack surfaces, and understand architectural patterns. MANDATORY for all source code analysis.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create todo items for each phase and agent that needs execution. Mark items as "in_progress" when working on them and "completed" when done.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication mechanisms, map attack surfaces, and understand architectural patterns. MANDATORY for all source code analysis.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create todo items for each phase and agent that needs execution. Mark items as "in_progress" when working on them and "completed" when done.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 </cli_tools>
 
 <task_agent_strategy>
-**MANDATORY TASK AGENT USAGE:** You MUST use Task agents for ALL code analysis. Direct file reading is PROHIBITED.
+**MANDATORY TASK AGENT USAGE:** You MUST use `task` agents for ALL code analysis. Direct file reading is PROHIBITED.
 
 **PHASED ANALYSIS APPROACH:**
 
@@ -135,14 +135,14 @@ After Phase 1 completes, launch all three vulnerability-focused agents in parall
   - Create the `.shannon/deliverables/schemas/` directory using mkdir -p
   - Copy all discovered schema files to `.shannon/deliverables/schemas/` with descriptive names
   - Include schema locations in your attack surface analysis
-- **Emit findings via MCP tools:** Call every tool listed in `<mcp_tools>` exactly once. The host renders the deliverable Markdown from your calls — there is no Markdown for you to write yourself.
+- **Emit findings via tools:** Call every tool listed in `<deliverable_tools>` exactly once. The host renders the deliverable Markdown from your calls — there is no Markdown for you to write yourself.
 
 **EXECUTION PATTERN:**
-1. **Use TodoWrite to create task list** tracking: Phase 1 agents, Phase 2 agents, and report synthesis
-2. **Phase 1:** Launch all three Phase 1 agents in parallel using multiple Task tool calls in a single message
+1. **Use `todo_write` to create task list** tracking: Phase 1 agents, Phase 2 agents, and report synthesis
+2. **Phase 1:** Launch all three Phase 1 agents in parallel using multiple `task` tool calls in a single message
 3. **Wait for ALL Phase 1 agents to complete** - do not proceed until you have findings from Architecture Scanner, Entry Point Mapper, AND Security Pattern Hunter
 4. **Mark Phase 1 todos as completed** and review all findings
-5. **Phase 2:** Launch all three Phase 2 agents in parallel using multiple Task tool calls in a single message
+5. **Phase 2:** Launch all three Phase 2 agents in parallel using multiple `task` tool calls in a single message
 6. **Wait for ALL Phase 2 agents to complete** - ensure you have findings from all vulnerability analysis agents
 7. **Mark Phase 2 todos as completed**
 8. **Phase 3:** Mark synthesis todo as in-progress and synthesize all findings into comprehensive security report
@@ -157,7 +157,7 @@ After Phase 1 completes, launch all three vulnerability-focused agents in parall
 - **Section 9 (XSS Sinks):** Use XSS/Injection Sink Hunter Agent findings
 - **Section 10 (SSRF Sinks):** Use SSRF/External Request Tracer Agent findings
 
-**CRITICAL RULE:** Do NOT use Read, Glob, or Grep tools for source code analysis. All code examination must be delegated to Task agents.
+**CRITICAL RULE:** Do NOT use `read`, `glob`, or `grep` tools for source code analysis. All code examination must be delegated to `task` agents.
 </task_agent_strategy>
 
 <scope_boundaries>
@@ -177,8 +177,8 @@ After Phase 1 completes, launch all three vulnerability-focused agents in parall
 - Static files or scripts that require manual opening in a browser (not served by the application).
 </scope_boundaries>
 
-<mcp_tools>
-**Emit your findings exclusively via the `pre-recon-collector` MCP tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
+<deliverable_tools>
+**Emit your findings exclusively via the deliverable tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
 
 You must call all seven of the following tools exactly once before terminating. Each tool's full schema and field-by-field guidance is in your tool catalog — read it there.
 
@@ -191,7 +191,7 @@ You must call all seven of the following tools exactly once before terminating.
 - `set_ssrf_sinks` — SSRF sinks grouped by sink category (Section 10). Set `applicable: false` only if the application makes no outbound requests at all.
 
 Each `set_*` tool is one-shot. Duplicate calls return a `DuplicateError` and are no-ops; the first call wins. Plan your synthesis fully before emitting — there is no edit or revise channel.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
@@ -201,11 +201,11 @@ Each `set_*` tool is one-shot. Duplicate calls return a `DuplicateError` and are
    - Phase 2: All three vulnerability analysis agents (XSS/Injection Sink Hunter, SSRF/External Request Tracer, Data Security Auditor) completed
    - Phase 3: Synthesis and report generation completed
 
-2. **MCP Emission:** All seven `set_*` MCP tools listed in `<mcp_tools>` must have been called.
+2. **Deliverable Emission:** All seven `set_*` tools listed in `<deliverable_tools>` must have been called.
 
 3. **Schemas Side Output:** `.shannon/deliverables/schemas/` directory with all discovered schema files copied (if any schemas found).
 
-4. **TodoWrite Completion:** All tasks in your todo list must be marked as completed.
+4. **`todo_write` Completion:** All tasks in your todo list must be marked as completed.
 
 **ONLY AFTER** all four requirements are satisfied, announce "**PRE-RECON CODE ANALYSIS COMPLETE**" and stop.
 

apps/worker/prompts/recon.txt

@@ -73,11 +73,11 @@ A component is **out-of-scope** if it **cannot** be invoked through the running
 
 <cli_tools>
 Please use these tools for the following use cases:
-- Task tool: **MANDATORY for ALL source code analysis.** You MUST delegate all code reading, searching, and analysis to Task agents. DO NOT use Read, Glob, or Grep tools for source code.
+- `task` tool: **MANDATORY for ALL source code analysis.** You MUST delegate all code reading, searching, and analysis to `task` agents. DO NOT use `read`, `glob`, or `grep` tools for source code.
 - **Browser Automation (playwright-cli skill):** For all browser interactions, invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 
-**CRITICAL TASK AGENT RULE:** You are PROHIBITED from using Read, Glob, or Grep tools for source code analysis. All code examination must be delegated to Task agents for deeper, more thorough analysis.
+**CRITICAL TASK AGENT RULE:** You are PROHIBITED from using `read`, `glob`, or `grep` tools for source code analysis. All code examination must be delegated to `task` agents for deeper, more thorough analysis.
 </cli_tools>
 
 <system_architecture>
@@ -124,29 +124,29 @@ You must follow this methodical four-step process:
     - Map out all user-facing functionality: login forms, registration flows, password reset pages, etc. Document the multi-step processes.
     - Observe the network requests to identify primary API calls.
 
-3.  **Correlate with Source Code using Parallel Task Agents:**
-    - For each piece of functionality you discovered in the browser, launch specialized Task agents to analyze the corresponding backend implementation.
-    - Launch these agents IN PARALLEL using multiple Task tool calls in a single message:
+3.  **Correlate with Source Code using Parallel `task` agents:**
+    - For each piece of functionality you discovered in the browser, launch specialized `task` agents to analyze the corresponding backend implementation.
+    - Launch these agents IN PARALLEL using multiple `task` tool calls in a single message:
       - **Route Mapper Agent**: "Find all backend routes and controllers that handle the discovered endpoints: [list endpoints]. Map each endpoint to its exact handler function with file paths and line numbers."
       - **Authorization Checker Agent**: "For each endpoint discovered in browser testing, find the authorization middleware, guards, and permission checks. Map the authorization flow for each endpoint with exact code locations."
       - **Input Validator Agent**: "Analyze the input validation logic for all discovered form fields and API parameters. Find validation rules, sanitization, and data processing for each input with exact file paths."
       - **Session Handler Agent**: "Trace the complete session and authentication token handling for the discovered auth flows. Map session creation, storage, validation, and destruction with exact code locations."
 
-3.5 **Authorization Architecture Analysis using Task Agents:**
+3.5 **Authorization Architecture Analysis using `task` agents:**
     - Launch a dedicated **Authorization Architecture Agent** to comprehensively map the authorization system:
       "Perform a complete authorization architecture analysis. Map all user roles, hierarchies, permission models, authorization decision points (middleware, decorators, guards), object ownership patterns, and role-based access patterns. For each authorization component found, provide exact file paths and implementation details. Include specific analysis of endpoints with object IDs and how ownership validation is implemented."
 
-4.  **Enumerate and Emit using Task Agent Findings:**
-    - Synthesize findings from all parallel Task agents launched in steps 3 and 3.5
-    - Use their exact file paths, code locations, and analysis to populate the MCP tool calls
-    - Cross-reference browser observations with Task agent source code findings to create comprehensive attack surface maps
-    - Emit findings via the MCP tools listed in `<mcp_tools>` — the renderer produces the deliverable Markdown from your tool calls
+4.  **Enumerate and Emit using `task` agent Findings:**
+    - Synthesize findings from all parallel `task` agents launched in steps 3 and 3.5
+    - Use their exact file paths, code locations, and analysis to populate the tool calls
+    - Cross-reference browser observations with `task` agent source code findings to create comprehensive attack surface maps
+    - Emit findings via the tools listed in `<deliverable_tools>` — the renderer produces the deliverable Markdown from your tool calls
 </systematic_approach>
 
-<mcp_tools>
-**Emit your findings exclusively via the `recon-collector` MCP tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
+<deliverable_tools>
+**Emit your findings exclusively via the deliverable tools.** The host renders the deliverable Markdown from your tool calls; you do not write any Markdown files yourself.
 
-**When to emit.** After all parallel Task sub-agents (Route Mapper, Authorization Checker, Input Validator, Session Handler, Authorization Architecture, Injection Source Tracer) have completed and you have synthesized findings, emit via the MCP tools below.
+**When to emit.** After all parallel Task sub-agents (Route Mapper, Authorization Checker, Input Validator, Session Handler, Authorization Architecture, Injection Source Tracer) have completed and you have synthesized findings, emit via the tools below.
 
 **Required tools — call all nine before terminating.** Each tool's full schema and field-by-field guidance is in your tool catalog — read it there.
 
@@ -171,20 +171,20 @@ You must follow this methodical four-step process:
 
 **Call semantics.** Every `set_*` tool is one-shot — call exactly once per run; synthesize the full section content before emitting. Duplicate `set_*` calls return `"already called"` and are no-ops. `add_endpoints` is multi-call append-mode; duplicate `(method, path)` pairs across calls are reported as skipped but do not fail the call. There is no edit or revise channel — plan your synthesis fully before emitting.
 
-**Injection Source Tracer dispatch (for Section 9).** Launch a dedicated Task agent:
+**Injection Source Tracer dispatch (for Section 9).** Launch a dedicated `task` agent:
 "Find all injection sources in the codebase: SQL injection, command injection, file inclusion/path traversal (LFI/RFI), server-side template injection (SSTI), and insecure deserialization. Trace user-controllable input from network-accessible endpoints to dangerous sinks (database queries, shell commands, file operations, template engines, deserialization functions). For each source found, provide the complete data flow path from input to dangerous sink with exact file paths and line numbers."
 
 **Network Surface Focus (applies to every tool):** Only emit components, endpoints, input vectors, and injection sources that are reachable through the target web application's network interface. Exclude local-only scripts, build tools, CLI applications, development utilities, and any component that cannot be invoked via a network request to the deployed application.
-</mcp_tools>
+</deliverable_tools>
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
 1. **Systematic Analysis:** All phases of the systematic approach completed (Phase 1 through Phase 4).
-2. **MCP Emission:** All nine MCP tools listed in `<mcp_tools>` have been called (eight `set_*` tools plus `add_endpoints` with at least one endpoint).
-3. **TodoWrite Completion:** All tasks in your todo list marked completed.
+2. **Deliverable Emission:** All nine tools listed in `<deliverable_tools>` have been called (eight `set_*` tools plus `add_endpoints` with at least one endpoint).
+3. **`todo_write` Completion:** All tasks in your todo list marked completed.
 
 **ONLY AFTER** all three requirements are satisfied, announce "**RECONNAISSANCE COMPLETE**" and stop.
 
-**CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the host renders the deliverable from your MCP tool calls and it contains everything needed.
+**CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the host renders the deliverable from your tool calls and it contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/report-executive.txt

@@ -1,113 +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}}
-{{DESCRIPTION}}
+- **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/shared/_code-path-rules.txt

@@ -2,8 +2,8 @@
 Source-code routing. Each rule is tagged `[FILE]` (literal path) or `[GLOB]` (pattern). All paths are repository-relative.
 
 How to apply (focus rules):
-- For `[FILE]` entries — delegate analysis to the Task tool.
-- For `[GLOB]` entries — invoke the Glob tool to enumerate matches, then delegate analysis of every match to the Task tool.
+- For `[FILE]` entries — delegate analysis to the `task` tool.
+- For `[GLOB]` entries — use the `glob` tool to enumerate matches, then delegate analysis of every match to the `task` tool.
 
 Avoid — out of scope. Skip entirely; the tool layer will block any access attempts.
 {{CODE_RULES_AVOID}}

apps/worker/prompts/shared/login-instructions.txt

@@ -16,7 +16,7 @@ Execute the login flow based on the login_type specified in the configuration:
 2. Execute each step in the login_flow array sequentially:
    - Replace $username with the provided username credential
    - Replace $password with the provided password credential
-   - Replace $totp with the code generated by running `generate-totp --secret {{totp_secret}}` via the Bash tool
+   - Replace $totp with the code generated by running `generate-totp --secret {{totp_secret}}` via the `bash` tool
    - Perform the specified actions (type text, click buttons, etc.)
 3. Wait for page navigation/loading to complete after each critical step
 4. Handle any consent dialogs or "Continue as [user]" prompts by clicking appropriate buttons
@@ -30,7 +30,7 @@ Execute the login flow based on the login_type specified in the configuration:
    - Handle account selection if prompted
    - Replace $username with the provided username credential in provider login
    - Replace $password with the provided password credential in provider login
-   - Replace $totp with the code generated by running `generate-totp --secret {{totp_secret}}` via the Bash tool
+   - Replace $totp with the code generated by running `generate-totp --secret {{totp_secret}}` via the `bash` tool
    - Handle OAuth consent screens by clicking "Allow", "Accept", or "Continue", and hitting check boxes as needed.
    - Handle "Continue as [username]" dialogs by clicking "Continue"
 3. Wait for OAuth callback and final redirect to complete

apps/worker/prompts/validate-authentication.txt

@@ -12,7 +12,7 @@ This runs as a preflight check for our AI pentester. The user supplies credentia
 
 <cli_tools>
 - **Browser Automation (playwright-cli skill):** Invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **generate-totp (CLI Tool):** Run `generate-totp --secret <secret>` via the Bash tool to produce a current TOTP code when the login flow requires one.
+- **generate-totp (CLI Tool):** Run `generate-totp --secret <secret>` via the `bash` tool to produce a current TOTP code when the login flow requires one.
 </cli_tools>
 
 <login_instructions>

apps/worker/prompts/vuln-auth.txt

@@ -75,15 +75,15 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 <cli_tools>
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
-- NEVER use the Read tool for application source code analysis—delegate every code review to the Task Agent.
-- ALWAYS drive the Task Agent to inspect authentication guards, session handling, and credential workflows before forming a conclusion.
-- Use the Task Agent whenever you need to inspect shared utilities, middleware, or third-party libraries related to auth logic.
+- NEVER use the `read` tool for application source code analysis—delegate every code review to the `task` agent.
+- ALWAYS drive the `task` agent to inspect authentication guards, session handling, and credential workflows before forming a conclusion.
+- Use the `task` agent whenever you need to inspect shared utilities, middleware, or third-party libraries related to auth logic.
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication logic paths, and understand session/credential handling. MANDATORY for all source code analysis.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authentication logic paths, and understand session/credential handling. MANDATORY for all source code analysis.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows like password reset or registration), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint/flow that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint/flow that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
 </cli_tools>
 
 <data_format_specifications>
@@ -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>
@@ -112,11 +116,11 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 <methodology>
 # White-Box Vulnerability Analysis Procedure: Broken Authentication (AuthN-only)
 
-NOTE ON "FOR ALL": whenever an item begins with "for all …", use the TodoWrite tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
+NOTE ON "FOR ALL": whenever an item begins with "for all …", use the `todo_write` tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
 From `.shannon/deliverables/pre_recon_deliverable.md`, use Section 3 and 6 to help guide your tasks.
 
 ## 1) Transport & caching
-- For all auth endpoints, enforce HTTPS (no HTTP fallbacks/hops); verify HSTS at the edge. (for all: use TodoWrite tool to add each endpoint as a task)
+- For all auth endpoints, enforce HTTPS (no HTTP fallbacks/hops); verify HSTS at the edge. (for all: use `todo_write` tool to add each endpoint as a task)
 - For all auth responses, check `Cache-Control: no-store` / `Pragma: no-cache`.
 **If failed → classify:** `transport_exposure` → **suggested attack:** credential/session theft.
 
@@ -194,35 +198,36 @@ For each check you perform from the list above (Transport, Rate Limiting, Sessio
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 3 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
+<deliverable_tools>
+After completing your `todo_write` tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot tools. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
 **Tool catalog:**
 - `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
 - `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with auth-specific sub-fields: authentication method, session token details, password policy)
 - `set_safe_vectors` — Section 4 (Secure by Design: Validated Components)
+- `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
+The harness injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
-**Call semantics:** All 3 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
+**Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
 **Required vs recommended:**
 - `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-auth` agent reads.
-- `set_safe_vectors` is recommended. An empty array is acceptable on runs with no validated-secure components, but explicit emission is preferred over skipping.
+- `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure components or no constraint gaps, but explicit emission is preferred over skipping.
 
-**Relationship to the exploitation queue:** The exploitation queue (`auth_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 3 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
-</mcp_tools>
+**Relationship to the exploitation queue:** The exploitation queue (`auth_exploitation_queue.json`) is produced by calling the `submit_exploitation_queue` tool when your analysis is complete. The 4 tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</deliverable_tools>
 
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
 1.  **Systematic Analysis:** ALL relevant API endpoints and user-facing features identified in the reconnaissance deliverable must be analyzed for AuthN/AuthZ flaws.
-2.  **Deliverable Emission:** Call the 3 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` is recommended (an empty array is acceptable but explicit emission is preferred).
+2.  **Deliverable Emission:** Call the 4 tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays are acceptable but explicit emission is preferred).
 
-**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+**Note:** The exploitation queue is produced by calling the `submit_exploitation_queue` tool when your analysis is complete — separate from the tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the tool calls.
 
-**ONLY AFTER** both systematic analysis AND the required MCP tool calls have been completed, announce "**AUTH ANALYSIS COMPLETE**" and stop.
+**ONLY AFTER** both systematic analysis AND the required tool calls have been completed, announce "**AUTH ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/vuln-authz.txt

@@ -80,15 +80,15 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 <cli_tools>
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
-- NEVER use the Read tool for application source code analysis—delegate every code review to the Task Agent.
-- ALWAYS direct the Task Agent to follow authorization guard placement, role checks, and ownership validation before you reach a verdict.
-- Use the Task Agent whenever you need to inspect shared middleware, decorators, or policy modules involved in access control.
+- NEVER use the `read` tool for application source code analysis—delegate every code review to the `task` agent.
+- ALWAYS direct the `task` agent to follow authorization guard placement, role checks, and ownership validation before you reach a verdict.
+- Use the `task` agent whenever you need to inspect shared middleware, decorators, or policy modules involved in access control.
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authorization logic paths, and understand permission models. MANDATORY for all source code analysis.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace authorization logic paths, and understand permission models. MANDATORY for all source code analysis.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows and role-based access controls), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint that needs authorization analysis. Mark items as "in_progress" when working on them and "completed" when done.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create a todo item for each endpoint that needs authorization analysis. Mark items as "in_progress" when working on them and "completed" when done.
 </cli_tools>
 
 <data_format_specifications>
@@ -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>
@@ -126,7 +130,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 1) Horizontal Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Horizontal"*, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Horizontal"*, use the `todo_write` tool to create a task entry.
     
 - **Process:**
     - Start at the identified endpoint.
@@ -158,7 +162,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 2) Vertical Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`.shannon/deliverables/recon_deliverable.md` →  section 8 "Vertical"**, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` →  section 8 "Vertical"**, use the `todo_write` tool to create a task entry.
     
 - **Process:**
     - Start at the identified endpoint.
@@ -184,7 +188,7 @@ An **exploitable vulnerability** is a logical flaw in the code that represents a
 ### 3) Context / Workflow Authorization Analysis
 
 - **Create To Dos:**
-    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Context"**, use the TodoWrite tool to create a task entry.
+    For each item listed under **`.shannon/deliverables/recon_deliverable.md` → section 8 "Context"**, use the `todo_write` tool to create a task entry.
     
 - **Process:**
     - Start at the endpoint that represents a step in a workflow.
@@ -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).
 
 ---
@@ -272,8 +276,8 @@ For each analysis you perform from the lists above, you must make a final **verd
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
+<deliverable_tools>
+After completing your `todo_write` tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot tools. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
 **Tool catalog:**
 - `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
@@ -281,7 +285,7 @@ After completing your TodoWrite tasks and synthesizing findings, emit your speci
 - `set_safe_vectors` — Section 4 (vectors confirmed secure)
 - `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For authz specifically, when populating `set_safe_vectors`, the renderer maps `subject` to the "Endpoint" column header and `location` to the "Guard Location" column header.
+The harness injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For authz specifically, when populating `set_safe_vectors`, the renderer maps `subject` to the "Endpoint" column header and `location` to the "Guard Location" column header.
 
 **Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
@@ -289,21 +293,21 @@ The MCP SDK injects each tool's complete description and per-field guidance into
 - `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-authz` agent reads.
 - `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure endpoints or no constraint gaps, but explicit emission is preferred over skipping.
 
-**Relationship to the exploitation queue:** The exploitation queue (`authz_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
-</mcp_tools>
+**Relationship to the exploitation queue:** The exploitation queue (`authz_exploitation_queue.json`) is produced by calling the `submit_exploitation_queue` tool when your analysis is complete. The 4 tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</deliverable_tools>
 
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
-1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed".
-2. **Deliverable Emission:** Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
+1. **Todo Completion:** ALL tasks in your `todo_write` list must be marked as "completed".
+2. **Deliverable Emission:** Call the 4 tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+**Note:** The exploitation queue is produced by calling the `submit_exploitation_queue` tool when your analysis is complete — separate from the tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the tool calls.
 
-**ONLY AFTER** both todo completion AND the required MCP tool calls have been completed, announce "**AUTHORIZATION ANALYSIS COMPLETE**" and stop.
+**ONLY AFTER** both todo completion AND the required tool calls have been completed, announce "**AUTHORIZATION ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 
-**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit MCP deliverable calls before completing comprehensive testing of all authorization vectors.
+**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit deliverable calls before completing comprehensive testing of all authorization vectors.
 </conclusion_trigger>

apps/worker/prompts/vuln-injection.txt

@@ -35,7 +35,7 @@ Success criterion: Complete source-to-sink traces detailing path, sanitizers, si
 -   **Severity Context:** A structural flaw in a backend command, whether an SQL query or a shell command, is one of the most severe classes of vulnerability in a SaaS application. It undermines the foundational trust of the system by creating the *potential* for data exposure (SQLi) or direct server compromise (Command Injection).
 -   **Your Role is Precise:** Your sole responsibility is to identify and precisely document these structural command flaws. You prove the *potential* for compromise; the Exploitation phase confirms the *realized* compromise. Do not cross this boundary.
 -   **Code is Ground Truth:** Your analysis must be rooted in the application's code. An observed behavior is only a symptom; the insecure data flow within the code is the root cause you must identify.
--   **Thoroughness is Non-Negotiable:** An incomplete analysis is a failed analysis. Finding one flaw is merely the first data point. Your mission is only complete when **every potential data entry point** from the reconnaissance deliverable has been systematically analyzed and documented using the TodoWrite tool. **Do not terminate early.**
+-   **Thoroughness is Non-Negotiable:** An incomplete analysis is a failed analysis. Finding one flaw is merely the first data point. Your mission is only complete when **every potential data entry point** from the reconnaissance deliverable has been systematically analyzed and documented using the `todo_write` tool. **Do not terminate early.**
 </critical>
 
 <starting_context>
@@ -80,15 +80,15 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 <cli_tools>
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
-- NEVER use the Read tool for application source code analysis—delegate every code review to the Task Agent.
-- ALWAYS direct the Task Agent to trace tainted data flow, sanitization/encoding steps, and sink construction before you reach a verdict.
-- Use the Task Agent instead of Bash or Playwright when you need to inspect handlers, middleware, or shared utilities to follow an injection path.
+- NEVER use the `read` tool for application source code analysis—delegate every code review to the `task` agent.
+- ALWAYS direct the `task` agent to trace tainted data flow, sanitization/encoding steps, and sink construction before you reach a verdict.
+- Use the `task` agent instead of Bash or Playwright when you need to inspect handlers, middleware, or shared utilities to follow an injection path.
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, map query/command construction paths, and verify sanitization coverage. MANDATORY for all source code analysis.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, map query/command construction paths, and verify sanitization coverage. MANDATORY for all source code analysis.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows like password reset or registration), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each injection source that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create a todo item for each injection source that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
 </cli_tools>
 
 <data_format_specifications>
@@ -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>
@@ -125,7 +129,7 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
   - **Goal:** Prove whether untrusted input can influence the **structure** of a backend command (SQL or Shell) or reach sensitive **slots** without the correct defense. No live exploitation in this phase.
   - **1) Create a To Do for each Injection Source found in the Pre-Recon Deliverable
-		  - inside of .shannon/deliverables/pre_recon_deliverable.md under the section "7. Injection Sources (Command Injection and SQL Injection)" use the TodoWrite tool to create a task for each discovered Injection Source. 
+		  - inside of .shannon/deliverables/pre_recon_deliverable.md under the section "7. Injection Sources (Command Injection and SQL Injection)" use the `todo_write` tool to create a task for each discovered Injection Source. 
 		  - Note: All sources are marked as Tainted until they Hit a Santiization that matches the sink context. normalizers (lowercasing, trimming, JSON parse, schema decode) — still **tainted**.
     - **2) Trace Data Flow Paths from Source to Sink**
 		    - For each source, your goal is to identify every unique "Data Flow Path" to a database sink. A path is a distinct route the data takes through the code.
@@ -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.
@@ -283,8 +287,8 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
+<deliverable_tools>
+After completing your `todo_write` tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot tools. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
 **Tool catalog:**
 - `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
@@ -292,7 +296,7 @@ After completing your TodoWrite tasks and synthesizing findings, emit your speci
 - `set_safe_vectors` — Section 4 (vectors confirmed secure)
 - `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
+The harness injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
 **Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
@@ -300,21 +304,21 @@ The MCP SDK injects each tool's complete description and per-field guidance into
 - `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-injection` agent reads.
 - `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure vectors or no constraint gaps, but explicit emission is preferred over skipping.
 
-**Relationship to the exploitation queue:** The exploitation queue (`injection_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
-</mcp_tools>
+**Relationship to the exploitation queue:** The exploitation queue (`injection_exploitation_queue.json`) is produced by calling the `submit_exploitation_queue` tool when your analysis is complete. The 4 tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</deliverable_tools>
 
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
-1. **Todo Completion:** ALL tasks in your TodoWrite list must be marked as "completed".
-2. **Deliverable Emission:** Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
+1. **Todo Completion:** ALL tasks in your `todo_write` list must be marked as "completed".
+2. **Deliverable Emission:** Call the 4 tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+**Note:** The exploitation queue is produced by calling the `submit_exploitation_queue` tool when your analysis is complete — separate from the tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the tool calls.
 
-**ONLY AFTER** both todo completion AND the required MCP tool calls have been completed, announce "**INJECTION ANALYSIS COMPLETE**" and stop.
+**ONLY AFTER** both todo completion AND the required tool calls have been completed, announce "**INJECTION ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 
-**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit MCP deliverable calls before completing comprehensive testing of all input vectors.
+**FAILURE TO COMPLETE TODOS = INCOMPLETE ANALYSIS** - You will be considered to have failed the mission if you emit deliverable calls before completing comprehensive testing of all input vectors.
 </conclusion_trigger>

apps/worker/prompts/vuln-ssrf.txt

@@ -76,15 +76,15 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 <cli_tools>
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
-- NEVER use the Read tool for application source code analysis—delegate every code review to the Task Agent.
-- ALWAYS drive the Task Agent to map user-controlled input to outbound HTTP clients, validation layers, and network controls before declaring a result.
-- Use the Task Agent to inspect shared utilities, proxy helpers, and request builders instead of reading files directly.
+- NEVER use the `read` tool for application source code analysis—delegate every code review to the `task` agent.
+- ALWAYS drive the `task` agent to map user-controlled input to outbound HTTP clients, validation layers, and network controls before declaring a result.
+- Use the `task` agent to inspect shared utilities, proxy helpers, and request builders instead of reading files directly.
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace data flows, and understand HTTP client usage. MANDATORY for all source code analysis.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`task` agent (Code Analysis):** Your primary tool. Use it to ask targeted questions about the source code, trace data flows, and understand HTTP client usage. MANDATORY for all source code analysis.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 - **Browser Automation (playwright-cli skill):** For browser interactions with the live web application (multi-step flows involving URL redirection or proxy functionality), invoke the `playwright-cli` skill to learn available commands. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each SSRF sink that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create a todo item for each SSRF sink that needs analysis. Mark items as "in_progress" when working on them and "completed" when done.
 </cli_tools>
 
 <data_format_specifications>
@@ -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>
@@ -114,7 +118,7 @@ An **exploitable vulnerability** is a data flow where user-controlled input infl
 <methodology>
 # White-Box Vulnerability Analysis Procedure: Server-Side Request Forgery (SSRF)
 
-NOTE ON "FOR ALL": whenever an item begins with "for all …", use the TodoWrite tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
+NOTE ON "FOR ALL": whenever an item begins with "for all …", use the `todo_write` tool to create a separate task for each relevant endpoint/flow that needs to be analyzed.
 From `.shannon/deliverables/pre_recon_deliverable.md`, use Section 10 (SSRF Sinks) to guide your tasks.
 
 ## 1) Identify HTTP Client Usage Patterns
@@ -169,7 +173,7 @@ From `.shannon/deliverables/pre_recon_deliverable.md`, use Section 10 (SSRF Sink
 
 Inside `.shannon/deliverables/pre_recon_deliverable.md` under section `##10. SSRF Sinks##`.
 
-Use the TodoWrite tool to create a task for each discovered sink (any server-side request composed even partially from user input).
+Use the `todo_write` tool to create a task for each discovered sink (any server-side request composed even partially from user input).
 
 ---
 
@@ -243,35 +247,36 @@ For each check you perform from the list above, you must make a final **verdict*
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 3 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
+<deliverable_tools>
+After completing your `todo_write` tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot tools. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
 **Tool catalog:**
 - `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
 - `set_strategic_intelligence` — Section 3 (Strategic Intelligence for Exploitation, with SSRF-specific sub-fields: HTTP client library, request architecture, internal services)
 - `set_safe_vectors` — Section 4 (Secure by Design: Validated Components)
+- `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
+The harness injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects.
 
-**Call semantics:** All 3 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
+**Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
 **Required vs recommended:**
 - `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-ssrf` agent reads.
-- `set_safe_vectors` is recommended. An empty array is acceptable on runs with no validated-secure components, but explicit emission is preferred over skipping.
+- `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure components or no constraint gaps, but explicit emission is preferred over skipping.
 
-**Relationship to the exploitation queue:** The exploitation queue (`ssrf_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 3 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
-</mcp_tools>
+**Relationship to the exploitation queue:** The exploitation queue (`ssrf_exploitation_queue.json`) is produced by calling the `submit_exploitation_queue` tool when your analysis is complete. The 4 tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</deliverable_tools>
 
 
 <conclusion_trigger>
 **COMPLETION REQUIREMENTS (ALL must be satisfied):**
 
 1.  **Systematic Analysis:** ALL relevant API endpoints and request-making features identified in the reconnaissance deliverable must be analyzed for SSRF vulnerabilities.
-2.  **Deliverable Emission:** Call the 3 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` is recommended (an empty array is acceptable but explicit emission is preferred).
+2.  **Deliverable Emission:** Call the 4 tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays are acceptable but explicit emission is preferred).
 
-**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+**Note:** The exploitation queue is produced by calling the `submit_exploitation_queue` tool when your analysis is complete — separate from the tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the tool calls.
 
-**ONLY AFTER** both systematic analysis AND the required MCP tool calls have been completed, announce "**SSRF ANALYSIS COMPLETE**" and stop.
+**ONLY AFTER** both systematic analysis AND the required tool calls have been completed, announce "**SSRF ANALYSIS COMPLETE**" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

apps/worker/prompts/vuln-xss.txt

@@ -77,17 +77,17 @@ An **exploitable vulnerability** is a confirmed source-to-sink path where the en
 <cli_tools>
 
 **CRITICAL TOOL USAGE RESTRICTIONS:**
-- NEVER use the Read tool for application source code analysis - ALWAYS delegate to Task agents for examining .js, .ts, .py, .php files and application logic. You MAY use Read
+- NEVER use the `read` tool for application source code analysis - ALWAYS delegate to `task` agents for examining .js, .ts, .py, .php files and application logic. You MAY use Read
   tool directly for these files: `.shannon/deliverables/pre_recon_deliverable.md`, `.shannon/deliverables/recon_deliverable.md`
-- Direct the Task Agent to trace render contexts, sanitization coverage, and template/component boundaries before deciding on exploitability.
-- **ALWAYS delegate code analysis to Task agents**
+- Direct the `task` agent to trace render contexts, sanitization coverage, and template/component boundaries before deciding on exploitability.
+- **ALWAYS delegate code analysis to `task` agents**
 
 **Available Tools:**
-- **Task Agent (Code Analysis):** MANDATORY for all source code analysis and data flow tracing. Use this instead of Read tool for examining application code, models, controllers, and templates.
+- **`task` agent (Code Analysis):** MANDATORY for all source code analysis and data flow tracing. Use this instead of `read` tool for examining application code, models, controllers, and templates.
 - **Terminal (curl):** MANDATORY for testing HTTP-based XSS vectors and observing raw HTML responses. Use for reflected XSS testing and JSONP injection testing.
 - **Browser Automation (playwright-cli skill):** MANDATORY for testing DOM-based XSS and form submission vectors. Invoke the `playwright-cli` skill to learn available commands. Use for stored XSS testing and client-side payload execution verification. Always pass `-s={{PLAYWRIGHT_SESSION}}` to every command for session isolation.
-- **TodoWrite Tool:** Use this to create and manage your analysis task list. Create a todo item for each sink you need to analyze.
-- **Bash tool:** Use for creating directories, copying files, and other shell commands as needed.
+- **`todo_write` Tool:** Use this to create and manage your analysis task list. Create a todo item for each sink you need to analyze.
+- **`bash` tool:** Use for creating directories, copying files, and other shell commands as needed.
 </cli_tools>
 
 <data_format_specifications>
@@ -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>
@@ -124,11 +128,11 @@ Structure: The vulnerability JSON object MUST follow this exact format:
 - **Goal:** Identify vulnerable data flow paths by starting at the XSS sinks received from the recon phase and tracing backward to their sanitizations and sources. This approach is optimized for finding all types of XSS, especially complex Stored XSS patterns.
 - **Core Principle:** Data is assumed to be tainted until a context-appropriate output encoder (sanitization) is encountered on its path to the sink.
 
-### **1) Create a todo item for each XSS sink using the TodoWrite tool**
-Read .shannon/deliverables/pre_recon_deliverable.md section ##9. XSS Sinks and Render Contexts## and use the **TodoWrite tool** to create a todo item for each discovered sink-context pair that needs analysis.
+### **1) Create a todo item for each XSS sink using the `todo_write` tool**
+Read .shannon/deliverables/pre_recon_deliverable.md section ##9. XSS Sinks and Render Contexts## and use the **`todo_write` tool** to create a todo item for each discovered sink-context pair that needs analysis.
 
 ### **2) Trace Each Sink Backward (Backward Taint Analysis)**
-For each pending item in your todo list (managed via TodoWrite tool), trace the origin of the data variable backward from the sink through the application logic. Your goal is to find either a valid sanitizer or an untrusted source. Mark each todo item as completed after you've fully analyzed that sink.
+For each pending item in your todo list (managed via `todo_write` tool), trace the origin of the data variable backward from the sink through the application logic. Your goal is to find either a valid sanitizer or an untrusted source. Mark each todo item as completed after you've fully analyzed that sink.
 
 - **Early Termination for Secure Paths (Efficiency Rule):**
   - As you trace backward, if you encounter a sanitization/encoding function, immediately perform two checks:
@@ -205,8 +209,8 @@ This rulebook is used for the **Early Termination** check in Step 2.
 
 </methodology_and_domain_expertise>
 
-<mcp_tools>
-After completing your TodoWrite tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot MCP tools provided by the `vuln-collector` server. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
+<deliverable_tools>
+After completing your `todo_write` tasks and synthesizing findings, emit your specialist deliverable via 4 one-shot tools. Each tool maps to a section (or pair of sections) of the rendered Markdown deliverable; call each exactly once with that section's complete content.
 
 **Tool catalog:**
 - `set_findings_summary` — Section 1 (Executive Summary key outcome) and Section 2 (Dominant Vulnerability Patterns)
@@ -214,7 +218,7 @@ After completing your TodoWrite tasks and synthesizing findings, emit your speci
 - `set_safe_vectors` — Section 4 (vectors confirmed secure)
 - `set_blind_spots` — Section 5 (analysis constraints and blind spots)
 
-The MCP SDK injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For XSS specifically, when populating `set_safe_vectors`, include the optional `render_context` field on each entry (HTML_BODY, HTML_ATTRIBUTE, JAVASCRIPT_STRING, URL_PARAM, or CSS_VALUE).
+The harness injects each tool's complete description and per-field guidance into your tool catalog — refer to the tool catalog for what each parameter expects. For XSS specifically, when populating `set_safe_vectors`, include the optional `render_context` field on each entry (HTML_BODY, HTML_ATTRIBUTE, JAVASCRIPT_STRING, URL_PARAM, or CSS_VALUE).
 
 **Call semantics:** All 4 tools are one-shot — each may be called exactly once with the section's complete content. Duplicate calls return `"already called"` and are no-ops. There is no incremental/append mode; synthesize each section's full content in working memory before emitting.
 
@@ -222,19 +226,19 @@ The MCP SDK injects each tool's complete description and per-field guidance into
 - `set_findings_summary` and `set_strategic_intelligence` are required — call both before terminating. They produce the load-bearing content the downstream `exploit-xss` agent reads.
 - `set_safe_vectors` and `set_blind_spots` are recommended. Empty arrays are acceptable on runs with no validated-secure vectors or no constraint gaps, but explicit emission is preferred over skipping.
 
-**Relationship to the exploitation queue:** The exploitation queue (`xss_exploitation_queue.json`) is captured automatically from your final structured output at session end. The 4 MCP tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
-</mcp_tools>
+**Relationship to the exploitation queue:** The exploitation queue (`xss_exploitation_queue.json`) is produced by calling the `submit_exploitation_queue` tool when your analysis is complete. The 4 tools produce the analysis deliverable Markdown; the structured-output queue is separate and follows the `exploitation_queue_format` schema documented above.
+</deliverable_tools>
 
 
 <conclusion_trigger>
 COMPLETION REQUIREMENTS (ALL must be satisfied):
 
 1. Systematic Analysis: ALL input vectors identified from the reconnaissance deliverable must be analyzed.
-2. Deliverable Emission: Call the 4 MCP tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
+2. Deliverable Emission: Call the 4 tools (`set_findings_summary`, `set_strategic_intelligence`, `set_safe_vectors`, `set_blind_spots`) exactly once each with their respective section content. `set_findings_summary` and `set_strategic_intelligence` are required; `set_safe_vectors` and `set_blind_spots` are recommended (empty arrays acceptable but explicit emission is preferred).
 
-**Note:** The exploitation queue is captured automatically from your final structured output at session end — separate from the MCP tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the MCP tool calls.
+**Note:** The exploitation queue is produced by calling the `submit_exploitation_queue` tool when your analysis is complete — separate from the tools above. The analysis deliverable Markdown is rendered by the harness after your session ends from the tool calls.
 
-ONLY AFTER both systematic analysis AND the required MCP tool calls have been completed, announce "XSS ANALYSIS COMPLETE" and stop.
+ONLY AFTER both systematic analysis AND the required tool calls have been completed, announce "XSS ANALYSIS COMPLETE" and stop.
 
 **CRITICAL:** After announcing completion, STOP IMMEDIATELY. Do NOT output summaries, recaps, or explanations of your work — the deliverable contains everything needed.
 </conclusion_trigger>

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

@@ -1,404 +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.
-
-// Production Claude agent execution with retry, git checkpoints, and audit logging
-
-import { type JsonSchemaOutputFormat, query } from '@anthropic-ai/claude-agent-sdk';
-import { fs, path } from 'zx';
-import type { AuditSession } from '../audit/index.js';
-import { deliverablesDir } from '../paths.js';
-import { isRetryableError, PentestError } from '../services/error-handling.js';
-import { AGENT_VALIDATORS } from '../session-manager.js';
-import type { ActivityLogger } from '../types/activity-logger.js';
-import { isSpendingCapBehavior } from '../utils/billing-detection.js';
-import { formatTimestamp } from '../utils/formatting.js';
-import { Timer } from '../utils/metrics.js';
-import { createAuditLogger } from './audit-logger.js';
-import { dispatchMessage } from './message-handlers.js';
-import { type ModelTier, resolveModel, supportsAdaptiveThinking } from './models.js';
-import { detectExecutionContext, formatCompletionMessage, formatErrorOutput } from './output-formatters.js';
-import { createProgressManager } from './progress-manager.js';
-
-declare global {
-  var SHANNON_DISABLE_LOADER: boolean | undefined;
-}
-
-export interface ClaudePromptResult {
-  result?: string | null | undefined;
-  success: boolean;
-  duration: number;
-  turns?: number | undefined;
-  cost: number;
-  model?: string | undefined;
-  partialCost?: number | undefined;
-  apiErrorDetected?: boolean | undefined;
-  error?: string | undefined;
-  errorType?: string | undefined;
-  prompt?: string | undefined;
-  retryable?: boolean | undefined;
-  structuredOutput?: unknown;
-}
-
-function outputLines(lines: string[]): void {
-  for (const line of lines) {
-    console.log(line);
-  }
-}
-
-async function writeErrorLog(
-  err: Error & { code?: string; status?: number },
-  sourceDir: string,
-  fullPrompt: string,
-  duration: number,
-): Promise<void> {
-  try {
-    const errorLog = {
-      timestamp: formatTimestamp(),
-      agent: 'claude-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),
-      },
-      duration,
-    };
-    const logPath = path.join(deliverablesDir(sourceDir), 'error.log');
-    await fs.appendFile(logPath, `${JSON.stringify(errorLog)}\n`);
-  } catch {
-    // Best-effort error log writing - don't propagate failures
-  }
-}
-
-export async function validateAgentOutput(
-  result: ClaudePromptResult,
-  agentName: string | null,
-  sourceDir: string,
-  logger: ActivityLogger,
-): Promise<boolean> {
-  logger.info(`Validating ${agentName} agent output`);
-
-  try {
-    // Check if agent completed successfully (text result OR structured output)
-    if (!result.success || (!result.result && result.structuredOutput === undefined)) {
-      logger.error('Validation failed: Agent execution was unsuccessful');
-      return false;
-    }
-
-    // Get validator function for this agent
-    const validator = agentName ? AGENT_VALIDATORS[agentName as keyof typeof AGENT_VALIDATORS] : undefined;
-
-    if (!validator) {
-      logger.warn(`No validator found for agent "${agentName}" - assuming success`);
-      logger.info('Validation passed: Unknown agent with successful result');
-      return true;
-    }
-
-    logger.info(`Using validator for agent: ${agentName}`, { sourceDir });
-
-    // Apply validation function
-    const validationResult = await validator(sourceDir, logger);
-
-    if (validationResult) {
-      logger.info('Validation passed: Required files/structure present');
-    } else {
-      logger.error('Validation failed: Missing required deliverable files');
-    }
-
-    return validationResult;
-  } catch (error) {
-    const errMsg = error instanceof Error ? error.message : String(error);
-    logger.error(`Validation failed with error: ${errMsg}`);
-    return false;
-  }
-}
-
-// Low-level SDK execution. Handles message streaming, progress, and audit logging.
-// Exported for Temporal activities to call single-attempt execution.
-export async function runClaudePrompt(
-  prompt: string,
-  sourceDir: string,
-  context: string = '',
-  description: string = 'Claude analysis',
-  _agentName: string | null = null,
-  auditSession: AuditSession | null = null,
-  logger: ActivityLogger,
-  modelTier: ModelTier = 'medium',
-  outputFormat?: JsonSchemaOutputFormat,
-  apiKey?: string,
-  deliverablesSubdir?: string,
-  providerConfig?: import('../types/config.js').ProviderConfig,
-  mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>,
-): Promise<ClaudePromptResult> {
-  // 1. Initialize timing and prompt
-  const timer = new Timer(`agent-${description.toLowerCase().replace(/\s+/g, '-')}`);
-  const fullPrompt = context ? `${context}\n\n${prompt}` : prompt;
-
-  // 2. Set up progress and audit infrastructure
-  const execContext = detectExecutionContext(description);
-  const progress = createProgressManager(
-    { description, useCleanOutput: execContext.useCleanOutput },
-    global.SHANNON_DISABLE_LOADER ?? false,
-  );
-  const auditLogger = createAuditLogger(auditSession);
-
-  logger.info(`Running Claude Code: ${description}...`);
-
-  // 3. Build env vars to pass to SDK subprocesses
-  const sdkEnv: Record<string, string> = {
-    CLAUDE_CODE_MAX_OUTPUT_TOKENS: process.env.CLAUDE_CODE_MAX_OUTPUT_TOKENS || '64000',
-    PLAYWRIGHT_MCP_OUTPUT_DIR: deliverablesSubdir
-      ? path.join(sourceDir, path.dirname(deliverablesSubdir), '.playwright-cli')
-      : path.join(sourceDir, '.shannon', '.playwright-cli'),
-    // apiKey from ContainerConfig takes precedence over process.env
-    ...(apiKey && { ANTHROPIC_API_KEY: apiKey }),
-    // Deliverables subdir for save-deliverable CLI tool
-    ...(deliverablesSubdir && { SHANNON_DELIVERABLES_SUBDIR: deliverablesSubdir }),
-  };
-
-  // 3a. Apply structured provider config directly to sdkEnv (no process.env mutation)
-  if (providerConfig) {
-    switch (providerConfig.providerType) {
-      case 'bedrock':
-        sdkEnv.CLAUDE_CODE_USE_BEDROCK = '1';
-        if (providerConfig.awsRegion) sdkEnv.AWS_REGION = providerConfig.awsRegion;
-        if (providerConfig.awsAccessKeyId) sdkEnv.AWS_ACCESS_KEY_ID = providerConfig.awsAccessKeyId;
-        if (providerConfig.awsSecretAccessKey) sdkEnv.AWS_SECRET_ACCESS_KEY = providerConfig.awsSecretAccessKey;
-        break;
-      case 'vertex':
-        sdkEnv.CLAUDE_CODE_USE_VERTEX = '1';
-        if (providerConfig.gcpRegion) sdkEnv.CLOUD_ML_REGION = providerConfig.gcpRegion;
-        if (providerConfig.gcpProjectId) sdkEnv.ANTHROPIC_VERTEX_PROJECT_ID = providerConfig.gcpProjectId;
-        if (providerConfig.gcpCredentialsPath)
-          sdkEnv.GOOGLE_APPLICATION_CREDENTIALS = providerConfig.gcpCredentialsPath;
-        break;
-      case 'litellm_router':
-        if (providerConfig.baseUrl) sdkEnv.ANTHROPIC_BASE_URL = providerConfig.baseUrl;
-        if (providerConfig.authToken) sdkEnv.ANTHROPIC_AUTH_TOKEN = providerConfig.authToken;
-        break;
-      default:
-        // 'anthropic_api' or unset — apiKey already handled above
-        if (providerConfig.apiKey && !apiKey) sdkEnv.ANTHROPIC_API_KEY = providerConfig.apiKey;
-        break;
-    }
-  }
-
-  // 3b. Passthrough env vars not already set by providerConfig or apiKey
-  const passthroughVars = [
-    ...(!sdkEnv.ANTHROPIC_API_KEY ? ['ANTHROPIC_API_KEY'] : []),
-    'CLAUDE_CODE_OAUTH_TOKEN',
-    ...(!sdkEnv.ANTHROPIC_BASE_URL ? ['ANTHROPIC_BASE_URL'] : []),
-    ...(!sdkEnv.ANTHROPIC_AUTH_TOKEN ? ['ANTHROPIC_AUTH_TOKEN'] : []),
-    ...(!sdkEnv.CLAUDE_CODE_USE_BEDROCK ? ['CLAUDE_CODE_USE_BEDROCK'] : []),
-    ...(!sdkEnv.AWS_REGION ? ['AWS_REGION'] : []),
-    'AWS_BEARER_TOKEN_BEDROCK',
-    ...(!sdkEnv.CLAUDE_CODE_USE_VERTEX ? ['CLAUDE_CODE_USE_VERTEX'] : []),
-    ...(!sdkEnv.CLOUD_ML_REGION ? ['CLOUD_ML_REGION'] : []),
-    ...(!sdkEnv.ANTHROPIC_VERTEX_PROJECT_ID ? ['ANTHROPIC_VERTEX_PROJECT_ID'] : []),
-    ...(!sdkEnv.GOOGLE_APPLICATION_CREDENTIALS ? ['GOOGLE_APPLICATION_CREDENTIALS'] : []),
-    'HOME',
-    'PATH',
-    'PLAYWRIGHT_MCP_EXECUTABLE_PATH',
-  ];
-  for (const name of passthroughVars) {
-    const val = process.env[name];
-    if (val) {
-      sdkEnv[name] = val;
-    }
-  }
-
-  // 4. Configure SDK options
-  // Model override from providerConfig takes precedence over env-based resolveModel
-  const model = providerConfig?.modelOverrides?.[modelTier] ?? resolveModel(modelTier);
-  const adaptiveThinking = supportsAdaptiveThinking(model) && process.env.CLAUDE_ADAPTIVE_THINKING !== 'false';
-  const options = {
-    model,
-    maxTurns: 10_000,
-    cwd: sourceDir,
-    permissionMode: 'bypassPermissions' as const,
-    allowDangerouslySkipPermissions: true,
-    settingSources: ['user'] as ('user' | 'project' | 'local')[],
-    env: sdkEnv,
-    ...(adaptiveThinking && { thinking: { type: 'adaptive' as const } }),
-    ...(outputFormat && { outputFormat }),
-    ...(mcpServers && Object.keys(mcpServers).length > 0 && { mcpServers }),
-  };
-
-  if (!execContext.useCleanOutput) {
-    logger.info(`SDK Options: maxTurns=${options.maxTurns}, cwd=${sourceDir}, permissions=BYPASS`);
-  }
-
-  let turnCount = 0;
-  let result: string | null = null;
-  let apiErrorDetected = false;
-  let totalCost = 0;
-
-  progress.start();
-
-  try {
-    // 6. Process the message stream
-    const messageLoopResult = await processMessageStream(
-      fullPrompt,
-      options,
-      { execContext, description, progress, auditLogger, logger },
-      timer,
-    );
-
-    turnCount = messageLoopResult.turnCount;
-    result = messageLoopResult.result;
-    apiErrorDetected = messageLoopResult.apiErrorDetected;
-    totalCost = messageLoopResult.cost;
-    const model = messageLoopResult.model;
-
-    // === SPENDING CAP SAFEGUARD ===
-    // 7. Defense-in-depth: Detect spending cap that slipped through detectApiError().
-    // Uses consolidated billing detection from utils/billing-detection.ts
-    if (isSpendingCapBehavior(turnCount, totalCost, result || '')) {
-      throw new PentestError(
-        `Spending cap likely reached (turns=${turnCount}, cost=$0): ${result?.slice(0, 100)}`,
-        'billing',
-        true, // Retryable - Temporal will use 5-30 min backoff
-      );
-    }
-
-    // 8. Finalize successful result
-    const duration = timer.stop();
-
-    if (apiErrorDetected) {
-      logger.warn(`API Error detected in ${description} - will validate deliverables before failing`);
-    }
-
-    progress.finish(formatCompletionMessage(execContext, description, turnCount, duration));
-
-    return {
-      result,
-      success: true,
-      duration,
-      turns: turnCount,
-      cost: totalCost,
-      model,
-      partialCost: totalCost,
-      apiErrorDetected,
-      ...(messageLoopResult.structuredOutput !== undefined && {
-        structuredOutput: messageLoopResult.structuredOutput,
-      }),
-    };
-  } catch (error) {
-    // 9. Handle errors — log, write error file, return failure
-    const duration = timer.stop();
-
-    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)));
-    await writeErrorLog(err, sourceDir, fullPrompt, duration);
-
-    return {
-      error: err.message,
-      errorType: err.constructor.name,
-      prompt: `${fullPrompt.slice(0, 100)}...`,
-      success: false,
-      duration,
-      cost: totalCost,
-      retryable: isRetryableError(err),
-    };
-  }
-}
-
-interface MessageLoopResult {
-  turnCount: number;
-  result: string | null;
-  apiErrorDetected: boolean;
-  cost: number;
-  model?: string | undefined;
-  structuredOutput?: unknown;
-}
-
-interface MessageLoopDeps {
-  execContext: ReturnType<typeof detectExecutionContext>;
-  description: string;
-  progress: ReturnType<typeof createProgressManager>;
-  auditLogger: ReturnType<typeof createAuditLogger>;
-  logger: ActivityLogger;
-}
-
-async function processMessageStream(
-  fullPrompt: string,
-  options: NonNullable<Parameters<typeof query>[0]['options']>,
-  deps: MessageLoopDeps,
-  timer: Timer,
-): Promise<MessageLoopResult> {
-  const { execContext, description, progress, auditLogger, logger } = deps;
-  const HEARTBEAT_INTERVAL = 30000;
-
-  let turnCount = 0;
-  let result: string | null = null;
-  let apiErrorDetected = false;
-  let cost = 0;
-  let model: string | undefined;
-  let structuredOutput: unknown | undefined;
-  let lastHeartbeat = Date.now();
-
-  for await (const message of query({ prompt: fullPrompt, options })) {
-    // Heartbeat logging when loader is disabled
-    const now = Date.now();
-    if (global.SHANNON_DISABLE_LOADER && now - lastHeartbeat > HEARTBEAT_INTERVAL) {
-      logger.info(`[${Math.floor((now - timer.startTime) / 1000)}s] ${description} running... (Turn ${turnCount})`);
-      lastHeartbeat = now;
-    }
-
-    // Increment turn count for assistant messages
-    if (message.type === 'assistant') {
-      turnCount++;
-    }
-
-    const dispatchResult = await dispatchMessage(message as { type: string; subtype?: string }, turnCount, {
-      execContext,
-      description,
-      progress,
-      auditLogger,
-      logger,
-    });
-
-    if (dispatchResult.type === 'throw') {
-      throw dispatchResult.error;
-    }
-
-    if (dispatchResult.type === 'complete') {
-      result = dispatchResult.result;
-      cost = dispatchResult.cost;
-      if (dispatchResult.structuredOutput !== undefined) {
-        structuredOutput = dispatchResult.structuredOutput;
-      }
-      break;
-    }
-
-    if (dispatchResult.type === 'continue') {
-      if (dispatchResult.apiErrorDetected) {
-        apiErrorDetected = true;
-      }
-      if (dispatchResult.model) {
-        model = dispatchResult.model;
-      }
-    }
-  }
-
-  return {
-    turnCount,
-    result,
-    apiErrorDetected,
-    cost,
-    model,
-    ...(structuredOutput !== undefined && { structuredOutput }),
-  };
-}

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

@@ -0,0 +1,47 @@
+/**
+ * pi extension: enforce a bounded timeout on every `bash` tool call.
+ *
+ * pi's built-in bash tool accepts an optional `timeout` (in seconds) but applies
+ * NO default and NO upper bound — an unbounded command (e.g. a `playwright-cli`
+ * browser action that never returns) hangs the agent indefinitely. This extension
+ * registers a `tool_call` pre-execution handler that blocks any `bash` invocation
+ * that omits `timeout` or sets it above the maximum, returning a message that tells
+ * the model how to re-run the command correctly.
+ */
+
+import type { ExtensionAPI, ToolCallEvent, ToolCallEventResult } from '@earendil-works/pi-coding-agent';
+import { isToolCallEventType } from '@earendil-works/pi-coding-agent';
+
+/** Recommended timeout (seconds) suggested to the model when it omits one. */
+const DEFAULT_TIMEOUT_SECONDS = 120;
+
+/** Hard upper bound (seconds) a single bash command may run. */
+const MAX_TIMEOUT_SECONDS = 600;
+
+function evaluateBashTimeout(timeout: number | undefined): ToolCallEventResult | undefined {
+  const hasValidTimeout = typeof timeout === 'number' && Number.isFinite(timeout) && timeout > 0;
+  if (!hasValidTimeout) {
+    return {
+      block: true,
+      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.`,
+    };
+  }
+
+  if (timeout > MAX_TIMEOUT_SECONDS) {
+    return {
+      block: true,
+      reason: `bash 'timeout' ${timeout}s exceeds max ${MAX_TIMEOUT_SECONDS}s. Default ${DEFAULT_TIMEOUT_SECONDS}s, max ${MAX_TIMEOUT_SECONDS}s.`,
+    };
+  }
+
+  return undefined;
+}
+
+export default function bashTimeoutExtension(pi: ExtensionAPI): void {
+  pi.on('tool_call', (event: ToolCallEvent): ToolCallEventResult | undefined => {
+    if (!isToolCallEventType('bash', event)) {
+      return undefined;
+    }
+    return evaluateBashTimeout(event.input.timeout);
+  });
+}

apps/worker/src/ai/message-handlers.ts

@@ -1,408 +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.
-
-import type { SDKAssistantMessageError } from '@anthropic-ai/claude-agent-sdk';
-import { PentestError } from '../services/error-handling.js';
-import type { ActivityLogger } from '../types/activity-logger.js';
-import { ErrorCode } from '../types/errors.js';
-import { matchesBillingTextPattern } from '../utils/billing-detection.js';
-import { formatTimestamp } from '../utils/formatting.js';
-import type { AuditLogger } from './audit-logger.js';
-import {
-  filterJsonToolCalls,
-  formatAssistantOutput,
-  formatResultOutput,
-  formatToolResultOutput,
-  formatToolUseOutput,
-} from './output-formatters.js';
-import type { ProgressManager } from './progress-manager.js';
-import type {
-  ApiErrorDetection,
-  AssistantMessage,
-  AssistantResult,
-  ContentBlock,
-  ExecutionContext,
-  ModelRefusalFallbackMessage,
-  ResultData,
-  ResultMessage,
-  SystemInitMessage,
-  ToolResultData,
-  ToolResultMessage,
-  ToolUseData,
-  ToolUseMessage,
-} from './types.js';
-
-// Handles both array and string content formats from SDK
-function extractMessageContent(message: AssistantMessage): string {
-  const messageContent = message.message;
-
-  if (Array.isArray(messageContent.content)) {
-    return messageContent.content
-      .filter((c: ContentBlock) => c.type !== 'thinking' && c.type !== 'redacted_thinking')
-      .map((c: ContentBlock) => c.text || JSON.stringify(c))
-      .join('\n');
-  }
-
-  return String(messageContent.content);
-}
-
-// Extracts only text content (no tool_use JSON) to avoid false positives in error detection
-function extractTextOnlyContent(message: AssistantMessage): string {
-  const messageContent = message.message;
-
-  if (Array.isArray(messageContent.content)) {
-    return messageContent.content
-      .filter((c: ContentBlock) => c.type === 'text' || c.text)
-      .map((c: ContentBlock) => c.text || '')
-      .join('\n');
-  }
-
-  return String(messageContent.content);
-}
-
-function detectApiError(content: string): ApiErrorDetection {
-  if (!content || typeof content !== 'string') {
-    return { detected: false };
-  }
-
-  const lowerContent = content.toLowerCase();
-
-  // === BILLING/SPENDING CAP ERRORS (Retryable with long backoff) ===
-  // When Claude Code hits its spending cap, it returns a short message like
-  // "Spending cap reached resets 8am" instead of throwing an error.
-  // These should retry with 5-30 min backoff so workflows can recover when cap resets.
-  if (matchesBillingTextPattern(content)) {
-    return {
-      detected: true,
-      shouldThrow: new PentestError(
-        `Billing limit reached: ${content.slice(0, 100)}`,
-        'billing',
-        true, // RETRYABLE - Temporal will use 5-30 min backoff
-        {},
-        ErrorCode.SPENDING_CAP_REACHED,
-      ),
-    };
-  }
-
-  // === SESSION LIMIT (Non-retryable) ===
-  // Different from spending cap - usually means something is fundamentally wrong
-  if (lowerContent.includes('session limit reached')) {
-    return {
-      detected: true,
-      shouldThrow: new PentestError('Session limit reached', 'billing', false),
-    };
-  }
-
-  // Non-fatal API errors - detected but continue
-  if (lowerContent.includes('api error') || lowerContent.includes('terminated')) {
-    return { detected: true };
-  }
-
-  return { detected: false };
-}
-
-// Maps SDK structured error types to our error handling.
-function handleStructuredError(errorType: SDKAssistantMessageError, content: string): ApiErrorDetection {
-  switch (errorType) {
-    case 'billing_error':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Billing error (structured): ${content.slice(0, 100)}`,
-          'billing',
-          true, // Retryable with backoff
-          {},
-          ErrorCode.INSUFFICIENT_CREDITS,
-        ),
-      };
-    case 'rate_limit':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Rate limit hit (structured): ${content.slice(0, 100)}`,
-          'network',
-          true, // Retryable with backoff
-          {},
-          ErrorCode.API_RATE_LIMITED,
-        ),
-      };
-    case 'authentication_failed':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Authentication failed: ${content.slice(0, 100)}`,
-          'config',
-          false, // Not retryable - needs API key fix
-        ),
-      };
-    case 'server_error':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Server error (structured): ${content.slice(0, 100)}`,
-          'network',
-          true, // Retryable
-        ),
-      };
-    case 'invalid_request':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Invalid request: ${content.slice(0, 100)}`,
-          'config',
-          false, // Not retryable - needs code fix
-        ),
-      };
-    case 'max_output_tokens':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Max output tokens reached: ${content.slice(0, 100)}`,
-          'billing',
-          true, // Retryable - may succeed with different content
-        ),
-      };
-    case 'overloaded':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Anthropic API overloaded (structured): ${content.slice(0, 100)}`,
-          'network',
-          true, // Retryable with backoff
-        ),
-      };
-    case 'model_not_found':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Model not found: ${content.slice(0, 100)}`,
-          'config',
-          false, // Not retryable - model ID is misconfigured
-        ),
-      };
-    case 'oauth_org_not_allowed':
-      return {
-        detected: true,
-        shouldThrow: new PentestError(
-          `Organization not allowed for this credential: ${content.slice(0, 100)}`,
-          'config',
-          false, // Not retryable - needs credential/org fix
-        ),
-      };
-    default:
-      return { detected: true };
-  }
-}
-
-function handleAssistantMessage(message: AssistantMessage, turnCount: number): AssistantResult {
-  const content = extractMessageContent(message);
-  const cleanedContent = filterJsonToolCalls(content);
-
-  // Prefer structured error field from SDK, fall back to text-sniffing
-  // Use text-only content for error detection to avoid false positives
-  // from tool_use JSON (e.g. security reports containing "usage limit")
-  let errorDetection: ApiErrorDetection;
-  if (message.error) {
-    errorDetection = handleStructuredError(message.error, content);
-  } else {
-    const textOnlyContent = extractTextOnlyContent(message);
-    errorDetection = detectApiError(textOnlyContent);
-  }
-
-  const result: AssistantResult = {
-    content,
-    cleanedContent,
-    apiErrorDetected: errorDetection.detected,
-    logData: {
-      turn: turnCount,
-      content,
-      timestamp: formatTimestamp(),
-    },
-  };
-
-  // Only add shouldThrow if it exists (exactOptionalPropertyTypes compliance)
-  if (errorDetection.shouldThrow) {
-    result.shouldThrow = errorDetection.shouldThrow;
-  }
-
-  return result;
-}
-
-// Final message of a query with cost/duration info
-function handleResultMessage(message: ResultMessage): ResultData {
-  const result: ResultData = {
-    result: message.result || null,
-    cost: message.total_cost_usd || 0,
-    duration_ms: message.duration_ms || 0,
-    permissionDenials: message.permission_denials?.length || 0,
-  };
-
-  // Only add subtype if it exists (exactOptionalPropertyTypes compliance)
-  if (message.subtype) {
-    result.subtype = message.subtype;
-  }
-
-  // Capture stop_reason for diagnostics (helps debug early stops, budget exceeded, etc.)
-  if (message.stop_reason !== undefined) {
-    result.stop_reason = message.stop_reason;
-    if (message.stop_reason && message.stop_reason !== 'end_turn') {
-      console.log(`    Stop reason: ${message.stop_reason}`);
-    }
-  }
-
-  if (message.structured_output !== undefined) {
-    result.structuredOutput = message.structured_output;
-  }
-
-  return result;
-}
-
-function handleToolUseMessage(message: ToolUseMessage): ToolUseData {
-  return {
-    toolName: message.name,
-    parameters: message.input || {},
-    timestamp: formatTimestamp(),
-  };
-}
-
-// Truncates long results for display (500 char limit), preserves full content for logging
-function handleToolResultMessage(message: ToolResultMessage): ToolResultData {
-  const content = message.content;
-  const contentStr = typeof content === 'string' ? content : JSON.stringify(content, null, 2);
-
-  const displayContent =
-    contentStr.length > 500
-      ? `${contentStr.slice(0, 500)}...\n[Result truncated - ${contentStr.length} total chars]`
-      : contentStr;
-
-  return {
-    content,
-    displayContent,
-    timestamp: formatTimestamp(),
-  };
-}
-
-function outputLines(lines: string[]): void {
-  for (const line of lines) {
-    console.log(line);
-  }
-}
-
-export type MessageDispatchAction =
-  | { type: 'continue'; apiErrorDetected?: boolean | undefined; model?: string | undefined }
-  | { type: 'complete'; result: string | null; cost: number; structuredOutput?: unknown }
-  | { type: 'throw'; error: Error };
-
-export interface MessageDispatchDeps {
-  execContext: ExecutionContext;
-  description: string;
-  progress: ProgressManager;
-  auditLogger: AuditLogger;
-  logger: ActivityLogger;
-}
-
-// Dispatches SDK messages to appropriate handlers and formatters
-export async function dispatchMessage(
-  message: { type: string; subtype?: string },
-  turnCount: number,
-  deps: MessageDispatchDeps,
-): Promise<MessageDispatchAction> {
-  const { execContext, description, progress, auditLogger, logger } = deps;
-
-  switch (message.type) {
-    case 'assistant': {
-      const assistantResult = handleAssistantMessage(message as AssistantMessage, turnCount);
-
-      if (assistantResult.shouldThrow) {
-        return { type: 'throw', error: assistantResult.shouldThrow };
-      }
-
-      if (assistantResult.cleanedContent.trim()) {
-        progress.stop();
-        outputLines(formatAssistantOutput(assistantResult.cleanedContent, execContext, turnCount, description));
-        progress.start();
-      }
-
-      await auditLogger.logLlmResponse(turnCount, assistantResult.content);
-
-      if (assistantResult.apiErrorDetected) {
-        logger.warn('API Error detected in assistant response');
-        return { type: 'continue', apiErrorDetected: true };
-      }
-
-      return { type: 'continue' };
-    }
-
-    case 'system': {
-      if (message.subtype === 'init') {
-        const initMsg = message as SystemInitMessage;
-        if (!execContext.useCleanOutput) {
-          logger.info(`Model: ${initMsg.model}, Permission: ${initMsg.permissionMode}`);
-        }
-        return { type: 'continue', model: initMsg.model };
-      }
-      if (message.subtype === 'model_refusal_fallback') {
-        const fallback = message as ModelRefusalFallbackMessage;
-        const category = fallback.api_refusal_category ?? 'policy';
-        await auditLogger.logNote(
-          'model-fallback',
-          `Model refused (${category}); fell back ${fallback.original_model} → ${fallback.fallback_model}`,
-        );
-        return { type: 'continue' };
-      }
-      return { type: 'continue' };
-    }
-
-    case 'user':
-    case 'tool_progress':
-    case 'tool_use_summary':
-    case 'auth_status':
-      return { type: 'continue' };
-
-    case 'tool_use': {
-      const toolData = handleToolUseMessage(message as unknown as ToolUseMessage);
-      outputLines(formatToolUseOutput(toolData.toolName, toolData.parameters));
-      await auditLogger.logToolStart(toolData.toolName, toolData.parameters);
-      return { type: 'continue' };
-    }
-
-    case 'tool_result': {
-      const toolResultData = handleToolResultMessage(message as unknown as ToolResultMessage);
-      outputLines(formatToolResultOutput(toolResultData.displayContent));
-      await auditLogger.logToolEnd(toolResultData.content);
-      return { type: 'continue' };
-    }
-
-    case 'result': {
-      const resultData = handleResultMessage(message as ResultMessage);
-      outputLines(formatResultOutput(resultData, !execContext.useCleanOutput));
-
-      if (resultData.subtype === 'error_max_structured_output_retries') {
-        return {
-          type: 'throw',
-          error: new PentestError(
-            'Structured output validation failed after max retries',
-            'validation',
-            true,
-            {},
-            ErrorCode.OUTPUT_VALIDATION_FAILED,
-          ),
-        };
-      }
-
-      return {
-        type: 'complete' as const,
-        result: resultData.result,
-        cost: resultData.cost,
-        ...(resultData.structuredOutput !== undefined && { structuredOutput: resultData.structuredOutput }),
-      };
-    }
-
-    default:
-      logger.info(`Unhandled message type: ${message.type}`);
-      return { type: 'continue' };
-  }
-}

apps/worker/src/ai/models.ts

@@ -5,47 +5,338 @@
 // as published by the Free Software Foundation.
 
 /**
- * Model tier definitions and resolution.
+ * 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 via ANTHROPIC_SMALL_MODEL / ANTHROPIC_MEDIUM_MODEL / ANTHROPIC_LARGE_MODEL,
- * which works across all providers (direct, Bedrock, Vertex).
+ *   SHANNON_AI_MODEL=<provider>:<model-id>
+ *
+ * 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.
  */
 
-export type ModelTier = 'small' | 'medium' | 'large';
+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';
 
-const DEFAULT_MODELS: Readonly<Record<ModelTier, string>> = {
-  small: 'claude-haiku-4-5-20251001',
-  medium: 'claude-sonnet-4-6',
-  large: 'claude-opus-4-8',
-};
+/**
+ * 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;
 
-/** Resolve a model tier to a concrete model ID. */
-export function resolveModel(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;
-  }
+export type CuratedProviderId = (typeof CURATED_PROVIDERS)[number];
+
+function isCuratedProvider(value: string): value is CuratedProviderId {
+  return (CURATED_PROVIDERS as readonly string[]).includes(value);
 }
 
-/** 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);
+/** 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'],
+};
+
+/** 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;
 }
 
 /**
- * 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.
+ * 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 isFableModel(model: string): boolean {
-  return /fable/i.test(model);
+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;
+  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 API key primed into the ModelRuntime's credential store. */
+  apiKey?: string;
+}
+
+/**
+ * Collect the API key and optional endpoint override for a provider. A curated
+ * provider's own variables win, then the generic SHANNON_AI_API_KEY. Bedrock is
+ * excluded — it authenticates through its AWS_ variables, which pi reads directly.
+ */
+export function resolveProviderCredentials(providerId: string): ProviderCredentials {
+  const credentials: ProviderCredentials = {};
+
+  const namedVars = isCuratedProvider(providerId) ? PROVIDER_API_KEY_ENV[providerId] : [];
+  for (const name of namedVars) {
+    const value = process.env[name];
+    if (value) {
+      credentials.apiKey = value;
+      break;
+    }
+  }
+  if (!credentials.apiKey && providerId !== 'amazon-bedrock' && process.env[GENERIC_API_KEY_ENV]) {
+    credentials.apiKey = process.env[GENERIC_API_KEY_ENV];
+  }
+  if (process.env.SHANNON_AI_BASE_URL) credentials.baseUrl = process.env.SHANNON_AI_BASE_URL;
+
+  return credentials;
+}
+
+/**
+ * In-memory credential store holding the selected provider's API key.
+ *
+ * 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.
+ */
+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>;
+  modelRuntime: ModelRuntime;
+  modelId: string;
+  providerId: string;
+}
+
+/**
+ * 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.
+ */
+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 { compat: _responsesCompat, ...withoutCompat } = model;
+  return { ...withoutCompat, baseUrl, api: OPENAI_FORMATS['chat-completions'] };
+}
+
+/**
+ * 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 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/output-formatters.ts

@@ -4,36 +4,31 @@
 // it under the terms of the GNU Affero General Public License version 3
 // as published by the Free Software Foundation.
 
+/**
+ * Human-readable console formatting for the agent executor.
+ *
+ * Driven by the pi harness event stream: `turn_end` (assistant text) and
+ * `tool_execution_start` (structured tool calls). Unlike the previous harness —
+ * where tool calls were tool_use JSON embedded in assistant text and had to be
+ * parsed out — pi delivers tool name + args as discrete events, so formatting is
+ * a direct mapping.
+ */
+
 import { AGENTS } from '../session-manager.js';
 import { extractAgentType, formatDuration } from '../utils/formatting.js';
-import type { ExecutionContext, ResultData } from './types.js';
+import type { ExecutionContext } from './types.js';
 
 interface ToolCallInput {
   url?: string;
-  element?: string;
-  key?: string;
-  fields?: unknown[];
-  text?: string;
-  action?: string;
-  description?: string;
   command?: string;
-  todos?: Array<{
-    status: string;
-    content: string;
-  }>;
+  description?: string;
+  path?: string;
+  todos?: Array<{ status: string; content: string }>;
   [key: string]: unknown;
 }
 
-interface ToolCall {
-  name: string;
-  input?: ToolCallInput;
-}
-
-/**
- * Get agent prefix for parallel execution
- */
+/** Agent prefix used to attribute output when parallel agents interleave on one stream. */
 export function getAgentPrefix(description: string): string {
-  // Map agent names to their prefixes
   const agentPrefixes: Record<string, string> = {
     'injection-vuln': '[Injection]',
     'xss-vuln': '[XSS]',
@@ -47,7 +42,6 @@ export function getAgentPrefix(description: string): string {
     'ssrf-exploit': '[SSRF]',
   };
 
-  // First try to match by agent name directly
   for (const [agentName, prefix] of Object.entries(agentPrefixes)) {
     const agent = AGENTS[agentName as keyof typeof AGENTS];
     if (agent && description.includes(agent.displayName)) {
@@ -55,7 +49,6 @@ export function getAgentPrefix(description: string): string {
     }
   }
 
-  // Fallback to partial matches for backwards compatibility
   if (description.includes('injection')) return '[Injection]';
   if (description.includes('xss')) return '[XSS]';
   if (description.includes('authz')) return '[Authz]'; // Check authz before auth
@@ -65,9 +58,7 @@ export function getAgentPrefix(description: string): string {
   return '[Agent]';
 }
 
-/**
- * Extract domain from URL for display
- */
+/** Extract domain from URL for display. */
 function extractDomain(url: string): string {
   try {
     const urlObj = new URL(url);
@@ -77,11 +68,8 @@ function extractDomain(url: string): string {
   }
 }
 
-/**
- * Format playwright-cli commands into clean progress indicators
- */
+/** Format a playwright-cli command (run via the bash tool) into a clean progress indicator. */
 function formatBrowserAction(command: string): string | null {
-  // Extract subcommand after optional session flag (e.g., "playwright-cli -s=session1 navigate https://example.com")
   const match = command.match(/playwright-cli\s+(?:-s=\S+\s+)?(\S+)(?:\s+(.*))?/);
   if (!match) return null;
 
@@ -151,26 +139,19 @@ function formatBrowserAction(command: string): string | null {
   }
 }
 
-/**
- * Summarize TodoWrite updates into clean progress indicators
- */
+/** Summarize a todo_write update into a clean progress indicator. */
 function summarizeTodoUpdate(input: ToolCallInput | undefined): string | null {
   if (!input?.todos || !Array.isArray(input.todos)) {
     return null;
   }
 
   const todos = input.todos;
-  const completed = todos.filter((t) => t.status === 'completed');
-  const inProgress = todos.filter((t) => t.status === 'in_progress');
-
-  // Show recently completed tasks
-  const recent = completed.at(-1);
+  const recent = todos.filter((t) => t.status === 'completed').at(-1);
   if (recent) {
     return `✅ ${recent.content}`;
   }
 
-  // Show current in-progress task
-  const current = inProgress.at(0);
+  const current = todos.filter((t) => t.status === 'in_progress').at(0);
   if (current) {
     return `🔄 ${current.content}`;
   }
@@ -178,69 +159,6 @@ function summarizeTodoUpdate(input: ToolCallInput | undefined): string | null {
   return null;
 }
 
-/**
- * Filter out JSON tool calls from content, with special handling for Task calls
- */
-export function filterJsonToolCalls(content: string | null | undefined): string {
-  if (!content || typeof content !== 'string') {
-    return content || '';
-  }
-
-  const lines = content.split('\n');
-  const processedLines: string[] = [];
-
-  for (const line of lines) {
-    const trimmed = line.trim();
-
-    // Skip empty lines
-    if (trimmed === '') {
-      continue;
-    }
-
-    // Check if this is a JSON tool call
-    if (trimmed.startsWith('{"type":"tool_use"')) {
-      try {
-        const toolCall = JSON.parse(trimmed) as ToolCall;
-
-        // Special handling for Task tool calls
-        if (toolCall.name === 'Task') {
-          const description = toolCall.input?.description || 'analysis agent';
-          processedLines.push(`🚀 Launching ${description}`);
-          continue;
-        }
-
-        // Special handling for TodoWrite tool calls
-        if (toolCall.name === 'TodoWrite') {
-          const summary = summarizeTodoUpdate(toolCall.input);
-          if (summary) {
-            processedLines.push(summary);
-          }
-          continue;
-        }
-
-        // Special handling for browser tool calls (playwright-cli via Bash)
-        if (toolCall.name === 'Bash') {
-          const command = toolCall.input?.command || '';
-          if (command.includes('playwright-cli')) {
-            const browserAction = formatBrowserAction(command);
-            if (browserAction) {
-              processedLines.push(browserAction);
-            }
-          }
-        }
-      } catch {
-        // If JSON parsing fails, treat as regular text
-        processedLines.push(line);
-      }
-    } else {
-      // Keep non-JSON lines (assistant text)
-      processedLines.push(line);
-    }
-  }
-
-  return processedLines.join('\n');
-}
-
 export function detectExecutionContext(description: string): ExecutionContext {
   const isParallelExecution = description.includes('vuln agent') || description.includes('exploit agent');
 
@@ -252,62 +170,69 @@ export function detectExecutionContext(description: string): ExecutionContext {
     description.includes('exploit agent');
 
   const agentType = extractAgentType(description);
-
   const agentKey = description.toLowerCase().replace(/\s+/g, '-');
 
   return { isParallelExecution, useCleanOutput, agentType, agentKey };
 }
 
+/** Format assistant turn text (from a pi `turn_end` event). */
 export function formatAssistantOutput(
-  cleanedContent: string,
+  text: string,
   context: ExecutionContext,
   turnCount: number,
   description: string,
 ): string[] {
-  if (!cleanedContent.trim()) {
+  if (!text.trim()) {
     return [];
   }
 
-  const lines: string[] = [];
-
   if (context.isParallelExecution) {
-    // Compact output for parallel agents with prefixes
-    const prefix = getAgentPrefix(description);
-    lines.push(`${prefix} ${cleanedContent}`);
-  } else {
-    // Full turn output for sequential agents
-    lines.push(`\n    Turn ${turnCount} (${description}):`);
-    lines.push(`    ${cleanedContent}`);
+    // Compact, attributed output for interleaved parallel agents.
+    return [`${getAgentPrefix(description)} ${text}`];
   }
-
-  return lines;
+  // Full turn output for sequential agents.
+  return [`\n    Turn ${turnCount} (${description}):`, `    ${text}`];
 }
 
-export function formatResultOutput(data: ResultData, showFullResult: boolean): string[] {
-  const lines: string[] = [];
+/**
+ * Format a pi `tool_execution_start` event into a clean one-line progress indicator.
+ *
+ * Maps the common tool surfaces — `task` (sub-agent delegation), `todo_write`
+ * (plan updates), `bash` (incl. playwright-cli browser actions), read-only file
+ * tools, and the structured collector/submit tools — to friendly lines. Returns
+ * `[]` when there's nothing worth surfacing (e.g. a todo update with no active item).
+ */
+export function formatToolCall(
+  toolName: string,
+  args: Record<string, unknown> | undefined,
+  context: ExecutionContext,
+  description: string,
+): string[] {
+  const input = (args ?? {}) as ToolCallInput;
+  let line: string | null;
 
-  lines.push(`\n    COMPLETED:`);
-  lines.push(`    Duration: ${(data.duration_ms / 1000).toFixed(1)}s, Cost: $${data.cost.toFixed(4)}`);
-
-  if (data.subtype === 'error_max_turns') {
-    lines.push(`    Stopped: Hit maximum turns limit`);
-  } else if (data.subtype === 'error_during_execution') {
-    lines.push(`    Stopped: Execution error`);
+  if (toolName === 'task') {
+    line = `🚀 Launching ${input.description ?? 'sub-agent'}`;
+  } else if (toolName === 'todo_write') {
+    line = summarizeTodoUpdate(input);
+  } else if (toolName === 'bash') {
+    const command = typeof input.command === 'string' ? input.command : '';
+    line = command.includes('playwright-cli') ? formatBrowserAction(command) : `💻 ${command.slice(0, 60)}`;
+  } else if (toolName === 'read' || toolName === 'grep' || toolName === 'find' || toolName === 'ls') {
+    const path = typeof input.path === 'string' ? ` ${input.path.slice(0, 60)}` : '';
+    line = `📖 ${toolName}${path}`;
+  } else if (toolName.startsWith('set_') || toolName.startsWith('add_') || toolName.startsWith('submit_')) {
+    line = `📊 ${toolName.replace(/_/g, ' ')}`;
+  } else {
+    line = `🔧 ${toolName}`;
   }
 
-  if (data.permissionDenials > 0) {
-    lines.push(`    ${data.permissionDenials} permission denials`);
-  }
+  if (!line) return [];
 
-  if (showFullResult && data.result && typeof data.result === 'string') {
-    if (data.result.length > 1000) {
-      lines.push(`    ${data.result.slice(0, 1000)}... [${data.result.length} total chars]`);
-    } else {
-      lines.push(`    ${data.result}`);
-    }
+  if (context.isParallelExecution) {
+    return [`${getAgentPrefix(description)} ${line}`];
   }
-
-  return lines;
+  return [`    ${line}`];
 }
 
 export function formatErrorOutput(
@@ -321,12 +246,11 @@ export function formatErrorOutput(
   const lines: string[] = [];
 
   if (context.isParallelExecution) {
-    const prefix = getAgentPrefix(description);
-    lines.push(`${prefix} Failed (${formatDuration(duration)})`);
+    lines.push(`${getAgentPrefix(description)} Failed (${formatDuration(duration)})`);
   } else if (context.useCleanOutput) {
     lines.push(`${context.agentType} failed (${formatDuration(duration)})`);
   } else {
-    lines.push(`  Claude Code failed: ${description} (${formatDuration(duration)})`);
+    lines.push(`  pi agent failed: ${description} (${formatDuration(duration)})`);
   }
 
   lines.push(`    Error Type: ${error.constructor.name}`);
@@ -352,35 +276,12 @@ export function formatCompletionMessage(
   duration: number,
 ): string {
   if (context.isParallelExecution) {
-    const prefix = getAgentPrefix(description);
-    return `${prefix} Complete (${turnCount} turns, ${formatDuration(duration)})`;
+    return `${getAgentPrefix(description)} Complete (${turnCount} turns, ${formatDuration(duration)})`;
   }
 
   if (context.useCleanOutput) {
     return `${context.agentType.charAt(0).toUpperCase() + context.agentType.slice(1)} complete! (${turnCount} turns, ${formatDuration(duration)})`;
   }
 
-  return `  Claude Code completed: ${description} (${turnCount} turns) in ${formatDuration(duration)}`;
-}
-
-export function formatToolUseOutput(toolName: string, input: Record<string, unknown> | undefined): string[] {
-  const lines: string[] = [];
-
-  lines.push(`\n    Using Tool: ${toolName}`);
-  if (input && Object.keys(input).length > 0) {
-    lines.push(`    Input: ${JSON.stringify(input, null, 2)}`);
-  }
-
-  return lines;
-}
-
-export function formatToolResultOutput(displayContent: string): string[] {
-  const lines: string[] = [];
-
-  lines.push(`    Tool Result:`);
-  if (displayContent) {
-    lines.push(`    ${displayContent}`);
-  }
-
-  return lines;
+  return `  pi agent completed: ${description} (${turnCount} turns) in ${formatDuration(duration)}`;
 }

apps/worker/src/ai/pi/permission-system.ts

@@ -0,0 +1,141 @@
+// 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.
+
+/**
+ * code_path "avoid" enforcement for the pi harness, delegated to the
+ * @gotgenes/pi-permission-system extension.
+ *
+ * Each `code_path` avoid is translated into the extension's cross-cutting `path`
+ * deny surface — the strongest gate, blocking file access (read/edit/write/grep/
+ * find/ls) AND recognized bash file commands (cat/grep/sed/…) on any matching path,
+ * across every tool and child `task` session, not overridable by a per-tool allow.
+ *
+ * `external_directory: allow` keeps the extension from gating the agent's legitimate
+ * access outside the working directory once it is loaded (the pentest agent shells
+ * out to tools/paths outside the mounted repo). When there are no avoids the config
+ * is removed so the executor skips loading the extension entirely.
+ */
+
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { getAgentDir } from '@earendil-works/pi-coding-agent';
+import type { DistributedConfig } from '../../types/config.js';
+
+const PERMISSION_EXTENSION_ID = 'pi-permission-system';
+
+/**
+ * Translate one avoid value into the extension's flat-wildcard `path` patterns.
+ *
+ * The extension's `*` already spans path separators (no `**` globstar), and tool
+ * paths are compared as absolute. A plain directory value is expanded to cover the
+ * directory itself and everything under it, in both cwd-relative and prefixed
+ * (absolute) positions. Glob values fold `**`→`*`; a `dir/*` contents glob also
+ * denies the directory entry itself.
+ */
+export function toPathPatterns(value: string): string[] {
+  // Strip only leading path prefixes ("/", "./", "../"); preserve a dotfile's dot
+  // (so `.env` stays `.env`, not `env`).
+  const base = value.replace(/^(?:\.{0,2}\/)+/, '').replace(/\/+$/, '');
+  if (!base) return [];
+
+  if (base.includes('*') || base.includes('?')) {
+    // The extension's `*` already spans path separators, so fold `**` to `*`.
+    const flat = base.replace(/\*\*\//g, '*/').replace(/\*\*/g, '*');
+    const tail = flat.replace(/^(?:\*\/)+/, '');
+    const patterns = [flat, `*/${tail}`];
+    // Depth-agnostic catch-all only for a bare-name tail (so `**/*.env` hits a
+    // root-level `.env`); a structured tail would over-match sibling names.
+    if (!tail.includes('/')) {
+      patterns.push(tail.startsWith('*') ? tail : `*${tail}`);
+    }
+    // A `dir/*` contents glob should also deny the directory entry itself — the
+    // contents patterns require a trailing segment and wouldn't match the folder.
+    if (flat.endsWith('/*')) {
+      const folder = flat.slice(0, -2);
+      if (folder && !folder.includes('*')) {
+        patterns.push(folder, `*/${folder}`);
+      }
+    }
+    return [...new Set(patterns)];
+  }
+
+  return [base, `${base}/*`, `*/${base}`, `*/${base}/*`];
+}
+
+interface PermissionSystemConfig {
+  permission: {
+    '*': 'allow';
+    path: Record<string, 'allow' | 'deny'>;
+    external_directory: 'allow';
+  };
+}
+
+/** Build the extension config that denies every avoid pattern across all tools. */
+export function buildPermissionConfig(patterns: readonly string[]): PermissionSystemConfig {
+  // Default allow first; deny entries are appended so they win (last match wins).
+  const pathRules: Record<string, 'allow' | 'deny'> = { '*': 'allow' };
+  for (const pattern of patterns) {
+    for (const expanded of toPathPatterns(pattern)) {
+      pathRules[expanded] = 'deny';
+    }
+  }
+  return {
+    permission: {
+      '*': 'allow',
+      path: pathRules,
+      external_directory: 'allow',
+    },
+  };
+}
+
+/** Path to the extension's global config under the agent directory. */
+export function permissionSystemConfigPath(agentDir: string): string {
+  return path.join(agentDir, 'extensions', PERMISSION_EXTENSION_ID, 'config.json');
+}
+
+/** True when a pi-permission-system config has been written (avoid rules exist). */
+export function permissionSystemConfigExists(agentDir: string): boolean {
+  return fs.existsSync(permissionSystemConfigPath(agentDir));
+}
+
+/**
+ * Sync the distributed config's `code_path` avoids into the extension's global
+ * config (`<agentDir>/extensions/pi-permission-system/config.json`). When there
+ * are no avoids the config is removed so the executor skips loading the extension.
+ *
+ * Global (not project) config is used deliberately: it loads synchronously at
+ * extension init without depending on a session_start/ctx, it keeps the config
+ * out of the scanned repo, and it is idempotent across the agents of one run.
+ */
+export function syncPermissionSystemConfig(config: DistributedConfig | null): void {
+  const configPath = permissionSystemConfigPath(getAgentDir());
+  const avoidRules = (config?.avoid ?? []).filter((r) => r.type === 'code_path');
+
+  if (avoidRules.length === 0) {
+    fs.rmSync(configPath, { force: true });
+    return;
+  }
+
+  // Single-repo (fixed mount): patterns are the raw avoid values.
+  const patterns = avoidRules.map((r) => r.value);
+  fs.mkdirSync(path.dirname(configPath), { recursive: true });
+  fs.writeFileSync(configPath, JSON.stringify(buildPermissionConfig(patterns), null, 2));
+}
+
+/**
+ * Absolute path to the installed @gotgenes/pi-permission-system package directory,
+ * suitable for `DefaultResourceLoader`'s `additionalExtensionPaths`. The loader
+ * reads the package's `pi.extensions` manifest and loads the extension itself.
+ *
+ * The package's `.` export points at its service module, so we resolve that and
+ * walk up to the package root. Throws if the package is not resolvable.
+ */
+export function permissionSystemPackageDir(): string {
+  const require = createRequire(import.meta.url);
+  const servicePath = require.resolve('@gotgenes/pi-permission-system');
+  return path.resolve(path.dirname(servicePath), '..');
+}

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

@@ -0,0 +1,435 @@
+// 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.
+
+// Production agent execution on the pi harness, with git checkpoints and audit logging.
+
+import os from 'node:os';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import {
+  type AgentSession,
+  type AgentSessionEvent,
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  type ResourceLoader,
+  SessionManager,
+  SettingsManager,
+  type Skill,
+  type ToolDefinition,
+} from '@earendil-works/pi-coding-agent';
+import { fs, path } from 'zx';
+import type { AuditSession } from '../../audit/index.js';
+import { BASH_TIMEOUT_EXTENSION_DIR, deliverablesDir } from '../../paths.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 { 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 { resolveModelSelection } from '../models.js';
+import {
+  detectExecutionContext,
+  formatAssistantOutput,
+  formatCompletionMessage,
+  formatErrorOutput,
+  formatToolCall,
+} from '../output-formatters.js';
+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;
+}
+
+/** Built-in pi tools enabled for every agent (custom tool names are appended). */
+const BUILTIN_TOOLS = ['read', 'bash', 'edit', 'write', 'grep', 'find', 'ls'];
+
+/** Build the playwright-cli Skill object injected for browser-using agents. */
+function buildPlaywrightSkill(): Skill {
+  const filePath =
+    process.env.PLAYWRIGHT_CLI_SKILL_PATH ?? path.join(os.homedir(), '.claude/skills/playwright-cli/SKILL.md');
+  const baseDir = path.dirname(filePath);
+  return {
+    name: 'playwright-cli',
+    description:
+      'Drive a real browser via the playwright-cli binary. Use for any task that navigates, clicks, ' +
+      'fills forms, takes screenshots, or reads live pages.',
+    filePath,
+    baseDir,
+    sourceInfo: { path: filePath, source: 'custom', scope: 'user', origin: 'top-level', baseDir },
+    disableModelInvocation: false,
+  };
+}
+
+async function buildResourceLoader(
+  cwd: string,
+  logger: ActivityLogger,
+  agentName: string | null,
+): Promise<ResourceLoader> {
+  // Always enforce bounded bash timeouts so an unbounded command cannot hang the agent.
+  const additionalExtensionPaths: string[] = [BASH_TIMEOUT_EXTENSION_DIR];
+  if (permissionSystemConfigExists(getAgentDir())) {
+    try {
+      additionalExtensionPaths.push(permissionSystemPackageDir());
+    } catch {
+      logger.warn(
+        'code_path deny config present but @gotgenes/pi-permission-system not resolvable — skipping enforcement',
+      );
+    }
+  }
+
+  // Only browser-driving agents get the playwright-cli skill; the rest run with no skills.
+  const loader = new DefaultResourceLoader({
+    cwd,
+    agentDir: getAgentDir(),
+    ...(additionalExtensionPaths.length > 0 && { additionalExtensionPaths }),
+    ...(isBrowserAgent(agentName)
+      ? {
+          skillsOverride: (base) => ({
+            skills: [buildPlaywrightSkill()],
+            diagnostics: base.diagnostics,
+          }),
+        }
+      : { noSkills: true }),
+  });
+  await loader.reload();
+  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;
+  error?: string | undefined;
+  errorType?: string | undefined;
+  prompt?: string | undefined;
+  retryable?: boolean | undefined;
+  structuredOutput?: unknown;
+}
+
+function outputLines(lines: string[]): void {
+  for (const line of lines) {
+    console.log(line);
+  }
+}
+
+async function writeErrorLog(
+  err: Error & { code?: string; status?: number },
+  sourceDir: string,
+  fullPrompt: string,
+  duration: number,
+): Promise<void> {
+  try {
+    const errorLog = {
+      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: isRetryableFailure(err) },
+      duration,
+    };
+    const logPath = path.join(deliverablesDir(sourceDir), 'error.log');
+    await fs.appendFile(logPath, `${JSON.stringify(errorLog)}\n`);
+  } catch {
+    // Best-effort error log writing - don't propagate failures
+  }
+}
+
+export async function validateAgentOutput(
+  result: PiPromptResult,
+  agentName: string | null,
+  sourceDir: string,
+  logger: ActivityLogger,
+): Promise<boolean> {
+  logger.info(`Validating ${agentName} agent output`);
+  try {
+    if (!result.success || (!result.result && result.structuredOutput === undefined)) {
+      logger.error('Validation failed: Agent execution was unsuccessful');
+      return false;
+    }
+    const validator = agentName ? AGENT_VALIDATORS[agentName as keyof typeof AGENT_VALIDATORS] : undefined;
+    if (!validator) {
+      logger.warn(`No validator found for agent "${agentName}" - assuming success`);
+      return true;
+    }
+    logger.info(`Using validator for agent: ${agentName}`, { sourceDir });
+    const validationResult = await validator(sourceDir, logger);
+    if (validationResult) {
+      logger.info('Validation passed: Required files/structure present');
+    } else {
+      logger.error('Validation failed: Missing required deliverable files');
+    }
+    return validationResult;
+  } catch (error) {
+    const errMsg = error instanceof Error ? error.message : String(error);
+    logger.error(`Validation failed with error: ${errMsg}`);
+    return false;
+  }
+}
+
+/** Concatenate the text blocks of an assistant message (skips thinking + tool calls). */
+function extractAssistantText(message: AgentMessage): string {
+  if (message.role !== 'assistant') return '';
+  const blocks = message.content as Array<{ type: string; text?: string }>;
+  return blocks
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text ?? '')
+    .join('\n');
+}
+
+// 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(
+  prompt: string,
+  sourceDir: string,
+  context: string = '',
+  description: string = 'Agent analysis',
+  agentName: string | null = null,
+  auditSession: AuditSession | null = null,
+  logger: ActivityLogger,
+  callerTools?: ToolDefinition[],
+  deliverablesSubdir?: string,
+  cancellationSignal?: AbortSignal,
+  submitTool?: CapturedSubmitTool,
+): Promise<PiPromptResult> {
+  // 1. Initialize timing and prompt. A submit tool appends its directive so the
+  //    instruction to call it lives with the tool, not in every prompt file.
+  const timer = new Timer(`agent-${description.toLowerCase().replace(/\s+/g, '-')}`);
+  const basePrompt = context ? `${context}\n\n${prompt}` : prompt;
+  const fullPrompt = submitTool?.directive ? basePrompt + submitTool.directive : basePrompt;
+
+  // 2. Set up progress and audit infrastructure
+  const execContext = detectExecutionContext(description);
+  const progress = createProgressManager(
+    { description, useCleanOutput: execContext.useCleanOutput },
+    global.SHANNON_DISABLE_LOADER ?? false,
+  );
+  const auditLogger = createAuditLogger(auditSession);
+
+  logger.info(`Running pi agent: ${description}...`);
+
+  // 3. Expose bash-invoked CLI tooling (playwright-cli, save-deliverable) to the
+  //    environment pi's bash tool inherits. These are constant per container, so
+  //    setting them on process.env is parallel-safe across this workflow's agents.
+  process.env.PLAYWRIGHT_MCP_OUTPUT_DIR = deliverablesSubdir
+    ? path.join(sourceDir, path.dirname(deliverablesSubdir), '.playwright-cli')
+    : path.join(sourceDir, '.shannon', '.playwright-cli');
+  if (deliverablesSubdir) process.env.SHANNON_DELIVERABLES_SUBDIR = deliverablesSubdir;
+
+  // 4. Resolve model + auth, then assemble the tool set (universal task/todo tools
+  //    plus any caller-supplied collector/submit tools).
+  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: ChildUsage = { cost: 0, inputTokens: 0, outputTokens: 0, cacheReadTokens: 0, cacheWriteTokens: 0 };
+  const customTools: ToolDefinition[] = [
+    createTaskTool({
+      model: selection.model,
+      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 }),
+    }),
+    createTodoWriteTool(auditLogger),
+    createGlobTool(sourceDir),
+    ...(callerTools ?? []),
+    ...(submitTool ? [submitTool.tool] : []),
+  ];
+  // pi's `tools` allowlist gates custom tools too — list every custom name.
+  const tools = [...BUILTIN_TOOLS, ...customTools.map((t) => t.name)];
+
+  let turnCount = 0;
+  let pendingError: PentestError | null = null;
+  // 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 {
+    ({ session } = await createAgentSession({
+      cwd: sourceDir,
+      model: selection.model,
+      tools,
+      customTools,
+      modelRuntime: selection.modelRuntime,
+      sessionManager: SessionManager.inMemory(),
+      // 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) => {
+      switch (event.type) {
+        case 'turn_end': {
+          turnCount += 1;
+          const msg = event.message;
+          const text = extractAssistantText(msg);
+          if (text.trim()) {
+            void auditLogger.logLlmResponse(turnCount, text);
+            progress.stop();
+            outputLines(formatAssistantOutput(text, execContext, turnCount, description));
+            progress.start();
+          }
+          if (msg.role === 'assistant' && msg.stopReason === 'error') {
+            pendingError = pendingError ?? providerTurnError(msg, 'Agent error', selection.model.contextWindow);
+          }
+          break;
+        }
+        case 'tool_execution_start': {
+          void auditLogger.logToolStart(event.toolName, event.args);
+          const toolLines = formatToolCall(
+            event.toolName,
+            event.args as Record<string, unknown>,
+            execContext,
+            description,
+          );
+          if (toolLines.length > 0) {
+            progress.stop();
+            outputLines(toolLines);
+            progress.start();
+          }
+          break;
+        }
+        case 'tool_execution_end':
+          void auditLogger.logToolEnd(event.result);
+          break;
+        case 'compaction_end':
+          if (!event.aborted && !event.willRetry && event.errorMessage) {
+            pendingError =
+              pendingError ??
+              new PentestError(`Context compaction failed: ${event.errorMessage.slice(0, 200)}`, 'unknown', true);
+          }
+          break;
+        default:
+          break;
+      }
+    });
+
+    // 6. Run the agent to completion (resolves at agent_end).
+    await session.prompt(fullPrompt);
+    session.dispose();
+
+    // 7. Surface any error captured during the run.
+    if (pendingError) throw pendingError;
+
+    // 8. Read usage/cost and final text.
+    const usage = totalUsage(session, childUsage);
+    const result = session.getLastAssistantText() ?? null;
+
+    const duration = timer.stop();
+    progress.finish(formatCompletionMessage(execContext, description, turnCount, duration));
+
+    // Capture the submit tool's structured payload so callers read it off the
+    // result instead of holding a reference to the tool.
+    const structuredOutput = submitTool?.getCaptured();
+
+    return {
+      result,
+      success: true,
+      duration,
+      turns: turnCount,
+      cost: usage.cost,
+      inputTokens: usage.inputTokens,
+      outputTokens: usage.outputTokens,
+      cacheReadTokens: usage.cacheReadTokens,
+      cacheWriteTokens: usage.cacheWriteTokens,
+      model: selection.model.id,
+      ...(structuredOutput !== undefined && { structuredOutput }),
+    };
+  } catch (error) {
+    // 10. Handle errors — log, write error file, return failure
+    const duration = timer.stop();
+    const err = error as Error & { code?: string; status?: number };
+    await auditLogger.logError(err, duration, turnCount);
+    progress.stop();
+    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 instanceof PentestError && err.code ? err.code : err.constructor.name,
+      prompt: `${fullPrompt.slice(0, 100)}...`,
+      success: false,
+      duration,
+      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/session-tools.ts

@@ -0,0 +1,116 @@
+// 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.
+
+/**
+ * Per-session custom tools registered for every agent: `todo_write` and `glob`.
+ *
+ * These replace harness built-ins that pi does not ship. `todo_write` is a
+ * full-state-replace planning scratchpad mirrored to the workflow log; `glob` is
+ * fast-glob file matching (pi has no `Glob` built-in).
+ */
+
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { fs, glob, path } from 'zx';
+
+import type { AuditLogger } from '../audit-logger.js';
+
+export interface TodoItem {
+  content: string;
+  status: 'pending' | 'in_progress' | 'completed';
+  activeForm: string;
+}
+
+function renderTodos(todos: readonly TodoItem[]): string {
+  const mark = (status: TodoItem['status']): string => {
+    if (status === 'completed') return 'x';
+    if (status === 'in_progress') return '~';
+    return ' ';
+  };
+  return todos.map((todo) => `[${mark(todo.status)}] ${todo.content}`).join('  ');
+}
+
+export function createTodoWriteTool(auditLogger: AuditLogger): ToolDefinition {
+  let current: TodoItem[] = [];
+
+  return defineTool({
+    name: 'todo_write',
+    label: 'Todo Write',
+    description:
+      'Use this tool to create and manage a structured task list for your current session. ' +
+      'Pass the complete todo list on every call; it replaces the stored list entirely. Each ' +
+      'todo has a status of pending, in_progress, or completed.',
+    promptSnippet: 'todo_write: create and manage a structured task list',
+    parameters: Type.Object({
+      todos: Type.Array(
+        Type.Object({
+          content: Type.String({ description: 'Imperative task description, e.g. "Map SSRF sinks".' }),
+          status: Type.Union([Type.Literal('pending'), Type.Literal('in_progress'), Type.Literal('completed')]),
+          activeForm: Type.String({ description: 'Present-continuous form, e.g. "Mapping SSRF sinks".' }),
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      current = params.todos as TodoItem[];
+      const completed = current.filter((todo) => todo.status === 'completed').length;
+      await auditLogger.logNote('todo', renderTodos(current));
+      return {
+        content: [
+          {
+            type: 'text' as const,
+            text: `Todos updated (${current.length} items, ${completed} completed).`,
+          },
+        ],
+        details: undefined,
+      };
+    },
+  });
+}
+
+export function createGlobTool(cwd: string): ToolDefinition {
+  return defineTool({
+    name: 'glob',
+    label: 'Glob',
+    description:
+      'Fast file pattern matching. Supports glob patterns like "**/*.ts" or "src/**/*.{js,ts}". ' +
+      'Returns matching file paths sorted by modification time, most recent first.',
+    promptSnippet: 'glob: find files by name pattern',
+    parameters: Type.Object({
+      pattern: Type.String({ description: 'The glob pattern to match files against.' }),
+      path: Type.Optional(Type.String({ description: 'Directory to search in. Omit for the repository root.' })),
+    }),
+    async execute(_toolCallId, params) {
+      const searchRoot = params.path ? path.resolve(cwd, params.path) : cwd;
+      const matches = await glob.globby(params.pattern, {
+        cwd: searchRoot,
+        absolute: true,
+        dot: true,
+        onlyFiles: true,
+        followSymbolicLinks: false,
+      });
+
+      if (matches.length === 0) {
+        return { content: [{ type: 'text' as const, text: 'No files found' }], details: undefined };
+      }
+
+      const withMtime = await Promise.all(
+        matches.map(async (file) => {
+          try {
+            return { file, mtime: (await fs.stat(file)).mtimeMs };
+          } catch {
+            return { file, mtime: 0 };
+          }
+        }),
+      );
+      withMtime.sort((a, b) => b.mtime - a.mtime);
+
+      return {
+        content: [{ type: 'text' as const, text: withMtime.map((match) => match.file).join('\n') }],
+        details: undefined,
+      };
+    },
+  });
+}

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

@@ -0,0 +1,159 @@
+// 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.
+
+/**
+ * Generic `task` tool — pi.dev ships no built-in Task tool, so this supplies the
+ * Task-delegation surface Shannon's prompts require.
+ *
+ * Shannon's prompts mandate Task delegation (recon source tracer; the vuln
+ * agents delegate *every* code review; the exploit agents delegate automation),
+ * so this tool is required for parity, not optional. It spawns a nested pi
+ * session with the parent's resolved model object (never a tier string — that
+ * would route sub-agents through hardcoded IDs and leak billing), the parent's
+ * resource loader, and a fixed child tool surface.
+ */
+
+import { type AssistantMessage, type Model, Type } from '@earendil-works/pi-ai';
+import {
+  createAgentSession,
+  defineTool,
+  getAgentDir,
+  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>;
+  /** Parent's model/auth runtime, reused so sub-agents share its resolved credential. */
+  modelRuntime: ModelRuntime;
+  resourceLoader: ResourceLoader;
+  cancellationSignal?: AbortSignal | undefined;
+  /**
+   * Reports the cost/tokens of each spawned sub-session back to the caller.
+   * Sub-agents run in their own pi sessions that the parent has no reference to,
+   * 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;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+  }) => void;
+}
+
+const CHILD_TOOLS = ['read', 'grep', 'find', 'ls', 'write', 'bash'];
+
+function textResult(text: string) {
+  return { content: [{ type: 'text' as const, text }], details: undefined };
+}
+
+export function createTaskTool(config: TaskToolContext): ToolDefinition {
+  const taskTool: ToolDefinition = defineTool({
+    name: 'task',
+    label: 'Task',
+    description:
+      'Delegate a focused task to a sub-agent that runs independently with its own tools and returns ' +
+      'the result. Use this to break complex work into smaller, parallelizable sub-tasks.',
+    executionMode: 'parallel',
+    promptSnippet: 'task - Delegate a focused task to a sub-agent with read, grep, find, ls, write, and bash.',
+    promptGuidelines: [
+      'Use the task tool to delegate focused work: code review, reconnaissance, automation scripting, validation.',
+      'Pass all necessary context in the "prompt" parameter — the sub-agent cannot see your conversation history.',
+      'The sub-agent can use read, grep, find, ls, write, and bash, but cannot call task or custom collector tools.',
+      'You can launch multiple task tool calls in a single message to run sub-tasks in parallel.',
+    ],
+    parameters: Type.Object({
+      prompt: Type.String({
+        description: 'The task for the sub-agent to perform. Include all necessary context.',
+      }),
+      description: Type.Optional(Type.String({ description: 'A short (3-5 word) description of the task.' })),
+    }),
+    async execute(_toolCallId, params) {
+      const agentDir = getAgentDir();
+      const { session: subSession } = await createAgentSession({
+        cwd: config.cwd,
+        agentDir,
+        resourceLoader: config.resourceLoader,
+        model: config.model,
+        tools: CHILD_TOOLS,
+        modelRuntime: config.modelRuntime,
+        sessionManager: SessionManager.inMemory(config.cwd),
+        settingsManager: SettingsManager.inMemory({
+          retry: PI_RETRY_SETTINGS,
+          compaction: { enabled: true },
+        }),
+      });
+
+      const abortChildSession = (): void => {
+        void subSession.abort().catch(() => {
+          // Parent logger is not available inside the tool; dispose still tears
+          // down the session if abort itself rejects.
+        });
+      };
+      const onCancellation = (): void => abortChildSession();
+      if (config.cancellationSignal?.aborted) {
+        abortChildSession();
+      } else {
+        config.cancellationSignal?.addEventListener('abort', onCancellation, { once: true });
+      }
+
+      let resultText = '';
+      let subCost = 0;
+      subSession.subscribe((event) => {
+        if (event.type === 'turn_end') {
+          const msg = event.message as AssistantMessage | undefined;
+          for (const block of msg?.content ?? []) {
+            if (block.type === 'text' && block.text) {
+              resultText += (resultText ? '\n' : '') + block.text;
+            }
+          }
+          if (msg?.usage?.cost?.total != null) subCost += msg.usage.cost.total;
+        }
+      });
+
+      let swallowedError: string | undefined;
+      try {
+        try {
+          await subSession.prompt(params.prompt);
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err);
+          resultText += `\n[Sub-agent error: ${errorMsg}]`;
+        }
+
+        swallowedError = subSession.state.errorMessage;
+        // 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: subStats.tokens.input,
+          outputTokens: subStats.tokens.output,
+          cacheReadTokens: subStats.tokens.cacheRead,
+          cacheWriteTokens: subStats.tokens.cacheWrite,
+        });
+      } finally {
+        config.cancellationSignal?.removeEventListener('abort', onCancellation);
+        subSession.dispose();
+      }
+
+      if (swallowedError && !resultText.includes(swallowedError)) {
+        resultText += `\n[Sub-agent error: ${swallowedError}]`;
+      }
+
+      return textResult(resultText || '[Sub-agent produced no output]');
+    },
+  });
+
+  return taskTool;
+}

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

@@ -5,196 +5,136 @@
 // as published by the Free Software Foundation.
 
 /**
- * Zod schema definitions for vulnerability exploitation queue structured outputs.
+ * TypeBox schemas + submit-tool factory for vulnerability exploitation queues.
  *
- * Each vuln agent returns a structured JSON response matching its schema.
- * The SDK validates the output against the JSON Schema generated from these Zod definitions.
+ * pi captures each vuln agent's structured queue via a `submit_exploitation_queue`
+ * custom tool whose parameters mirror the per-class schema below. Entry types are
+ * derived from the same schemas and consumed by the findings renderer.
  */
 
-import type { JsonSchemaOutputFormat } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
+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';
-
-// === Common Fields ===
+import type { CapturedSubmitTool } from './submit-tool.js';
 
 const ANALYSIS_NOTES_DESCRIPTION = 'Plain context for defenders (caveats, scope, what is at risk). Not attack steps.';
 
-function notesField(exploit: boolean) {
-  const f = z.string().optional();
-  return exploit ? f : f.describe(ANALYSIS_NOTES_DESCRIPTION);
+function optStr(description?: string) {
+  return Type.Optional(Type.String(description === undefined ? {} : { description }));
 }
 
-function makeBase(exploit: boolean) {
-  return z.object({
-    ID: z.string(),
-    vulnerability_type: z.string(),
-    externally_exploitable: z.boolean(),
-    confidence: z.string(),
-    notes: notesField(exploit),
-  });
-}
-
-// === Per-Vuln-Type Schemas (used for type inference; notes description is mode-agnostic for types) ===
-
-const baseVulnerability = makeBase(true);
-
-const InjectionVulnerability = baseVulnerability.extend({
-  source: z.string().optional(),
-  combined_sources: z.string().optional(),
-  path: z.string().optional(),
-  sink_call: z.string().optional(),
-  slot_type: z.string().optional(),
-  sanitization_observed: z.string().optional(),
-  concat_occurrences: z.string().optional(),
-  verdict: z.string().optional(),
-  mismatch_reason: z.string().optional(),
-  witness_payload: z.string().optional(),
-});
-
-const XssVulnerability = baseVulnerability.extend({
-  source: z.string().optional(),
-  source_detail: z.string().optional(),
-  path: z.string().optional(),
-  sink_function: z.string().optional(),
-  render_context: z.string().optional(),
-  encoding_observed: z.string().optional(),
-  verdict: z.string().optional(),
-  mismatch_reason: z.string().optional(),
-  witness_payload: z.string().optional(),
-});
-
-const AuthVulnerability = baseVulnerability.extend({
-  source_endpoint: z.string().optional(),
-  vulnerable_code_location: z.string().optional(),
-  missing_defense: z.string().optional(),
-  exploitation_hypothesis: z.string().optional(),
-  suggested_exploit_technique: z.string().optional(),
-});
-
-const SsrfVulnerability = baseVulnerability.extend({
-  source_endpoint: z.string().optional(),
-  vulnerable_parameter: z.string().optional(),
-  vulnerable_code_location: z.string().optional(),
-  missing_defense: z.string().optional(),
-  exploitation_hypothesis: z.string().optional(),
-  suggested_exploit_technique: z.string().optional(),
-});
-
-const AuthzVulnerability = baseVulnerability.extend({
-  endpoint: z.string().optional(),
-  vulnerable_code_location: z.string().optional(),
-  role_context: z.string().optional(),
-  guard_evidence: z.string().optional(),
-  side_effect: z.string().optional(),
-  reason: z.string().optional(),
-  minimal_witness: z.string().optional(),
-});
-
-// === Inferred Entry Types (consumed by renderer) ===
-
-export type InjectionFinding = z.infer<typeof InjectionVulnerability>;
-export type XssFinding = z.infer<typeof XssVulnerability>;
-export type AuthFinding = z.infer<typeof AuthVulnerability>;
-export type SsrfFinding = z.infer<typeof SsrfVulnerability>;
-export type AuthzFinding = z.infer<typeof AuthzVulnerability>;
-
-// === Convert to JSON Schema for SDK ===
-
-// NOTE: The SDK's AJV validator expects draft-07. Zod defaults to draft-2020-12 which
-// causes the SDK to silently skip structured output.
-function toOutputFormat(zodSchema: z.ZodType): JsonSchemaOutputFormat {
-  return { type: 'json_schema', schema: z.toJSONSchema(zodSchema, { target: 'draft-07' }) as Record<string, unknown> };
-}
-
-// === Per-Mode Output Format Builders ===
-// Two maps cached at module load; the only per-mode difference is the
-// description on the `notes` field, which steers the LLM's writing.
-
-function buildOutputFormats(exploit: boolean): Partial<Record<AgentName, JsonSchemaOutputFormat>> {
-  const base = makeBase(exploit);
+/**
+ * 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 {
-    'injection-vuln': toOutputFormat(
-      z.object({
-        vulnerabilities: z.array(
-          base.extend({
-            source: z.string().optional(),
-            combined_sources: z.string().optional(),
-            path: z.string().optional(),
-            sink_call: z.string().optional(),
-            slot_type: z.string().optional(),
-            sanitization_observed: z.string().optional(),
-            concat_occurrences: z.string().optional(),
-            verdict: z.string().optional(),
-            mismatch_reason: z.string().optional(),
-            witness_payload: z.string().optional(),
+    ID: Type.String(),
+    vulnerability_type: Type.String(),
+    externally_exploitable: Type.Boolean(),
+    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.',
           }),
-        ),
-      }),
-    ),
-    'xss-vuln': toOutputFormat(
-      z.object({
-        vulnerabilities: z.array(
-          base.extend({
-            source: z.string().optional(),
-            source_detail: z.string().optional(),
-            path: z.string().optional(),
-            sink_function: z.string().optional(),
-            render_context: z.string().optional(),
-            encoding_observed: z.string().optional(),
-            verdict: z.string().optional(),
-            mismatch_reason: z.string().optional(),
-            witness_payload: z.string().optional(),
-          }),
-        ),
-      }),
-    ),
-    'auth-vuln': toOutputFormat(
-      z.object({
-        vulnerabilities: z.array(
-          base.extend({
-            source_endpoint: z.string().optional(),
-            vulnerable_code_location: z.string().optional(),
-            missing_defense: z.string().optional(),
-            exploitation_hypothesis: z.string().optional(),
-            suggested_exploit_technique: z.string().optional(),
-          }),
-        ),
-      }),
-    ),
-    'ssrf-vuln': toOutputFormat(
-      z.object({
-        vulnerabilities: z.array(
-          base.extend({
-            source_endpoint: z.string().optional(),
-            vulnerable_parameter: z.string().optional(),
-            vulnerable_code_location: z.string().optional(),
-            missing_defense: z.string().optional(),
-            exploitation_hypothesis: z.string().optional(),
-            suggested_exploit_technique: z.string().optional(),
-          }),
-        ),
-      }),
-    ),
-    'authz-vuln': toOutputFormat(
-      z.object({
-        vulnerabilities: z.array(
-          base.extend({
-            endpoint: z.string().optional(),
-            vulnerable_code_location: z.string().optional(),
-            role_context: z.string().optional(),
-            guard_evidence: z.string().optional(),
-            side_effect: z.string().optional(),
-            reason: z.string().optional(),
-            minimal_witness: z.string().optional(),
-          }),
-        ),
-      }),
+          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),
   };
 }
 
-const OUTPUT_FORMATS_EXPLOIT = buildOutputFormats(true);
-const OUTPUT_FORMATS_ANALYSIS = buildOutputFormats(false);
+const injectionFields = {
+  source: optStr(),
+  combined_sources: optStr(),
+  path: optStr(),
+  sink_call: optStr(),
+  slot_type: optStr(),
+  sanitization_observed: optStr(),
+  concat_occurrences: optStr(),
+  verdict: optStr(),
+  mismatch_reason: optStr(),
+  witness_payload: optStr(),
+};
+
+const xssFields = {
+  source: optStr(),
+  source_detail: optStr(),
+  path: optStr(),
+  sink_function: optStr(),
+  render_context: optStr(),
+  encoding_observed: optStr(),
+  verdict: optStr(),
+  mismatch_reason: optStr(),
+  witness_payload: optStr(),
+};
+
+const authFields = {
+  source_endpoint: optStr(),
+  vulnerable_code_location: optStr(),
+  missing_defense: optStr(),
+  exploitation_hypothesis: optStr(),
+  suggested_exploit_technique: optStr(),
+};
+
+const ssrfFields = {
+  source_endpoint: optStr(),
+  vulnerable_parameter: optStr(),
+  vulnerable_code_location: optStr(),
+  missing_defense: optStr(),
+  exploitation_hypothesis: optStr(),
+  suggested_exploit_technique: optStr(),
+};
+
+const authzFields = {
+  endpoint: optStr(),
+  vulnerable_code_location: optStr(),
+  role_context: optStr(),
+  guard_evidence: optStr(),
+  side_effect: optStr(),
+  reason: optStr(),
+  minimal_witness: optStr(),
+};
+
+// === Per-entry schemas (single vulnerability). Entry types derive from these. ===
+
+const injectionEntry = () => Type.Object({ ...baseFields(true), ...injectionFields });
+const xssEntry = () => Type.Object({ ...baseFields(true), ...xssFields });
+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>>;
+export type SsrfFinding = Static<ReturnType<typeof ssrfEntry>>;
+export type AuthzFinding = Static<ReturnType<typeof authzEntry>>;
+
+const PER_TYPE_FIELDS: Partial<Record<AgentName, Record<string, ReturnType<typeof optStr>>>> = {
+  'injection-vuln': injectionFields,
+  'xss-vuln': xssFields,
+  'auth-vuln': authFields,
+  'ssrf-vuln': ssrfFields,
+  'authz-vuln': authzFields,
+};
 
 const VULN_AGENT_QUEUE_FILENAMES: Partial<Record<AgentName, string>> = {
   'injection-vuln': 'injection_exploitation_queue.json',
@@ -204,12 +144,53 @@ const VULN_AGENT_QUEUE_FILENAMES: Partial<Record<AgentName, string>> = {
   'authz-vuln': 'authz_exploitation_queue.json',
 };
 
-/** Returns the structured output format for a vuln agent, or undefined for non-vuln agents. */
-export function getOutputFormat(agentName: AgentName, exploit = true): JsonSchemaOutputFormat | undefined {
-  return (exploit ? OUTPUT_FORMATS_EXPLOIT : OUTPUT_FORMATS_ANALYSIS)[agentName];
+/** Build the TypeBox submit-tool parameters for a vuln agent, or undefined for non-vuln agents. */
+function queueSchema(agentName: AgentName, exploit: boolean): TObject | undefined {
+  const extra = PER_TYPE_FIELDS[agentName];
+  if (!extra) return undefined;
+  return Type.Object({
+    vulnerabilities: Type.Array(Type.Object({ ...baseFields(exploit), ...extra })),
+  });
 }
 
 /** Returns the queue filename for a vuln agent, or undefined for non-vuln agents. */
 export function getQueueFilename(agentName: AgentName): string | undefined {
   return VULN_AGENT_QUEUE_FILENAMES[agentName];
 }
+
+/** Build the pi submit tool that captures the exploitation queue for vuln agents. */
+export function createQueueSubmitTool(agentName: AgentName, exploit = true): CapturedSubmitTool | undefined {
+  const schema = queueSchema(agentName, exploit);
+  if (!schema) return undefined;
+
+  let captured: unknown | undefined;
+  return {
+    tool: defineTool({
+      name: 'submit_exploitation_queue',
+      label: 'Submit Exploitation Queue',
+      description:
+        'Submit the final structured list of analyzed vulnerabilities for this class. Call exactly once when analysis is complete.',
+      promptSnippet: 'submit_exploitation_queue: record the final structured findings list (call once)',
+      promptGuidelines: [
+        'You MUST call submit_exploitation_queue exactly once as your final action.',
+        'Include every analyzed finding in the vulnerabilities array.',
+      ],
+      parameters: schema,
+      async execute(_toolCallId, params) {
+        captured = params;
+        const count = Array.isArray((params as { vulnerabilities?: unknown }).vulnerabilities)
+          ? (params as { vulnerabilities: unknown[] }).vulnerabilities.length
+          : 0;
+        return {
+          content: [{ type: 'text' as const, text: `Recorded ${count} findings.` }],
+          details: params,
+          terminate: true,
+        };
+      },
+    }),
+    getCaptured: () => captured,
+    directive:
+      '\n\nYou MUST call the submit_exploitation_queue tool exactly once as your final action ' +
+      'to deliver your structured exploitation queue. Do not output JSON as text. Fill every required parameter.',
+  };
+}

apps/worker/src/ai/settings-writer.ts

@@ -1,41 +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.
-
-/**
- * Writes ~/.claude/settings.json with permissions.deny rules derived from
- * `code_path` avoid patterns. The SDK reads this via `settingSources: ['user']`;
- * deny rules fire even in `bypassPermissions` mode.
- */
-
-import os from 'node:os';
-import { fs, path } from 'zx';
-import type { DistributedConfig } from '../types/config.js';
-
-const FILE_TOOLS = ['Read', 'Edit'] as const;
-
-function denyEntriesFor(pattern: string): string[] {
-  const arg = `./${pattern.replace(/^[./]+/, '')}`;
-  return FILE_TOOLS.map((tool) => `${tool}(${arg})`);
-}
-
-export async function writeUserSettingsForCodePathAvoids(config: DistributedConfig | null): Promise<void> {
-  const avoidPatterns = (config?.avoid ?? []).filter((r) => r.type === 'code_path').map((r) => r.value);
-  const settingsPath = path.join(os.homedir(), '.claude', 'settings.json');
-
-  if (avoidPatterns.length === 0) {
-    await fs.remove(settingsPath);
-    return;
-  }
-
-  const settings = {
-    permissions: {
-      deny: avoidPatterns.flatMap(denyEntriesFor),
-    },
-  };
-
-  await fs.ensureDir(path.dirname(settingsPath));
-  await fs.writeJson(settingsPath, settings, { spaces: 2 });
-}

apps/worker/src/ai/submit-tool.ts

@@ -0,0 +1,60 @@
+// 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 { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+
+/**
+ * A pi custom submit tool plus the captured payload it records.
+ *
+ * pi ships no JSON-schema output format, so an agent that must return structured
+ * data does so by calling a purpose-built TypeBox tool. This bundles that tool
+ * with its capture accessor and the directive that instructs the model to call
+ * it. The executor owns the wiring — it registers the tool, appends the
+ * directive to the prompt, and reads `getCaptured()` back as `structuredOutput`
+ * — so callers never assemble it by hand.
+ */
+export interface CapturedSubmitTool {
+  readonly tool: ToolDefinition;
+  readonly getCaptured: () => unknown | undefined;
+  readonly directive?: string;
+}
+
+/**
+ * Build a `submit_result` tool from a raw JSON Schema, for agents whose result
+ * shape is not one of the built-in per-agent schemas (e.g. an out-of-tree agent
+ * with its own verdict schema). pi validates the tool call against `schema`
+ * before `execute()` runs, so a captured payload is already schema-valid — no
+ * separate validation pass is needed.
+ */
+export function createGenericSubmitTool(schema: Record<string, unknown>): CapturedSubmitTool {
+  let captured: unknown | undefined;
+  return {
+    tool: defineTool({
+      name: 'submit_result',
+      label: 'Submit Result',
+      description: 'Return your final structured answer. Call exactly once as your last action.',
+      promptSnippet: 'submit_result: deliver your structured answer (call once)',
+      promptGuidelines: [
+        'You MUST call submit_result exactly once as your final action.',
+        'Fill every required parameter. Do not output JSON as text.',
+      ],
+      parameters: Type.Unsafe(schema),
+      async execute(_toolCallId, params) {
+        captured = params;
+        return {
+          content: [{ type: 'text' as const, text: 'Result submitted.' }],
+          details: params,
+          terminate: true,
+        };
+      },
+    }),
+    getCaptured: () => captured,
+    directive:
+      '\n\nYou MUST call the submit_result tool exactly once as your final action ' +
+      'to deliver your structured answer. Do not output JSON as text. Fill every required parameter.',
+  };
+}

apps/worker/src/ai/types.ts

@@ -4,9 +4,7 @@
 // it under the terms of the GNU Affero General Public License version 3
 // as published by the Free Software Foundation.
 
-// Type definitions for Claude executor message processing pipeline
-
-import type { SDKAssistantMessageError } from '@anthropic-ai/claude-agent-sdk';
+// Shared display/formatting types for the agent executor output layer.
 
 export interface ExecutionContext {
   isParallelExecution: boolean;
@@ -14,99 +12,3 @@ export interface ExecutionContext {
   agentType: string;
   agentKey: string;
 }
-
-export interface AssistantResult {
-  content: string;
-  cleanedContent: string;
-  apiErrorDetected: boolean;
-  shouldThrow?: Error;
-  logData: {
-    turn: number;
-    content: string;
-    timestamp: string;
-  };
-}
-
-export interface ResultData {
-  result: string | null;
-  cost: number;
-  duration_ms: number;
-  subtype?: string;
-  stop_reason?: string | null;
-  permissionDenials: number;
-  structuredOutput?: unknown;
-}
-
-export interface ToolUseData {
-  toolName: string;
-  parameters: Record<string, unknown>;
-  timestamp: string;
-}
-
-export interface ToolResultData {
-  content: unknown;
-  displayContent: string;
-  timestamp: string;
-}
-
-export interface ContentBlock {
-  type?: string;
-  text?: string;
-  thinking?: string;
-  data?: string;
-}
-
-export interface AssistantMessage {
-  type: 'assistant';
-  error?: SDKAssistantMessageError;
-  message: {
-    content: ContentBlock[] | string;
-  };
-}
-
-export interface ResultMessage {
-  type: 'result';
-  result?: string;
-  total_cost_usd?: number;
-  duration_ms?: number;
-  subtype?: string;
-  stop_reason?: string | null;
-  permission_denials?: unknown[];
-  structured_output?: unknown;
-}
-
-export interface ToolUseMessage {
-  type: 'tool_use';
-  name: string;
-  input?: Record<string, unknown>;
-}
-
-export interface ToolResultMessage {
-  type: 'tool_result';
-  content?: unknown;
-}
-
-export interface ApiErrorDetection {
-  detected: boolean;
-  shouldThrow?: Error;
-}
-
-export interface SystemInitMessage {
-  type: 'system';
-  subtype: 'init';
-  model?: string;
-  permissionMode?: string;
-}
-
-/** Emitted when a model refuses a request and the SDK falls back to another model (e.g. Fable 5 routing cybersecurity tasks to Opus 4.8). */
-export interface ModelRefusalFallbackMessage {
-  type: 'system';
-  subtype: 'model_refusal_fallback';
-  original_model: string;
-  fallback_model: string;
-  api_refusal_category?: string | null;
-}
-
-export interface UserMessage {
-  type: 'user';
-}

apps/worker/src/audit/audit-session.ts

@@ -210,7 +210,7 @@ export class AuditSession {
   /**
    * Update session status
    */
-  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled'): Promise<void> {
+  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled' | 'partial'): Promise<void> {
     await this.ensureInitialized();
 
     const unlock = await sessionMutex.lock(this.sessionId);

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;
 }
@@ -57,7 +66,7 @@ interface SessionData {
     id: string;
     webUrl: string;
     repoPath?: string;
-    status: 'in-progress' | 'completed' | 'failed' | 'cancelled';
+    status: 'in-progress' | 'completed' | 'failed' | 'cancelled' | 'partial';
     createdAt: string;
     completedAt?: string;
     originalWorkflowId?: string; // First workflow that created this workspace
@@ -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) {
@@ -214,9 +236,9 @@ export class MetricsTracker {
         agent.checkpoint = result.checkpoint;
       }
     } else {
-      if (result.isFinalAttempt) {
-        agent.status = 'failed';
-      }
+      // A non-final failed attempt stays in-progress (Temporal will retry); only the
+      // terminal attempt (or an unqualified failure) marks the agent failed.
+      agent.status = result.isFinalAttempt === false ? 'in-progress' : 'failed';
     }
 
     // 7. Clear active timer
@@ -232,12 +254,12 @@ export class MetricsTracker {
   /**
    * Update session status
    */
-  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled'): Promise<void> {
+  async updateSessionStatus(status: 'in-progress' | 'completed' | 'failed' | 'cancelled' | 'partial'): Promise<void> {
     if (!this.data) return;
 
     this.data.session.status = status;
 
-    if (status === 'completed' || status === 'failed' || status === 'cancelled') {
+    if (status === 'completed' || status === 'failed' || status === 'cancelled' || status === 'partial') {
       this.data.session.completedAt = formatTimestamp();
     }
 

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

@@ -12,7 +12,6 @@
  */
 
 import fs from 'node:fs/promises';
-import { isFableModel, resolveModel } from '../ai/models.js';
 import { formatDuration, formatTimestamp } from '../utils/formatting.js';
 import { LogStream } from './log-stream.js';
 import { generateWorkflowLogPath, type SessionMetadata } from './utils.js';
@@ -31,7 +30,7 @@ export interface AgentMetricsSummary {
 }
 
 export interface WorkflowSummary {
-  status: 'completed' | 'failed' | 'cancelled';
+  status: 'completed' | 'failed' | 'cancelled' | 'partial';
   totalDurationMs: number;
   totalCostUsd: number;
   completedAgents: string[];
@@ -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: resolveModel(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'));
@@ -134,7 +120,7 @@ export class WorkflowLogger {
   }
 
   /**
-   * Format timestamp for log line (local time, human readable)
+   * Format timestamp for log line (UTC, human readable)
    */
   private formatLogTime(): string {
     const now = new Date();
@@ -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

@@ -5,10 +5,10 @@
 // as published by the Free Software Foundation.
 
 /**
- * Exploit Collector MCP Server (factory parameterized by vulnerability class
- * and per-run valid-ID set).
+ * Exploit Collector tool factory (parameterized by vulnerability class and
+ * per-run valid-ID set).
  *
- * Exposes a single Zod-validated MCP tool `add_exploit`, called once per
+ * Exposes a single TypeBox-validated tool `add_exploit`, called once per
  * processed vulnerability by the 5 exploit-* agents (injection, xss, auth,
  * ssrf, authz). After the agent terminates, the host harvests
  * collector.getAll() and runs exploit-renderer to produce
@@ -16,29 +16,29 @@
  * output.
  *
  * Schema shape:
- *   - The SDK tool() helper consumes a ZodRawShape (flat object), not a
- *     top-level discriminated union. The visible shape is therefore a single
- *     z.object with common fields required, status as a string enum, and
- *     per-status fields marked optional at the SDK layer. Each field's
- *     `.describe()` text explains when it applies.
+ *   - The visible parameter schema is a single Type.Object with common fields
+ *     required, status as a string union, and per-status fields marked optional
+ *     at the tool layer (TypeBox cannot express a top-level discriminated union
+ *     as the flat tool parameters). Each field's `description` text explains
+ *     when it applies.
  *   - True per-status field enforcement runs inside the tool handler via a
- *     z.discriminatedUnion('status', ...). Missing-field errors come back to
- *     the agent as structured Zod issues with retryable=true so it can fix
- *     and retry the call.
+ *     Type.Union([exploited, blocked]) re-validation using the TypeBox `Value`
+ *     API. Missing-field errors come back to the agent as structured issues
+ *     with retryable=true so it can fix and retry the call.
  *
- * Strict queue-ID validation: vulnerability_id is refined against the per-run
- * queue's known IDs at schema-build time. Hallucinated or typo'd IDs are
- * rejected with a structured Zod error that includes the valid-ID list,
- * letting the agent recover locally.
+ * Strict queue-ID validation: vulnerability_id is checked against the per-run
+ * queue's known IDs in the handler. Hallucinated or typo'd IDs are rejected
+ * with a structured error that includes the valid-ID list, letting the agent
+ * recover locally.
  *
- * Each Zod schema's field-level descriptions carry the bullet labels and
- * reproducibility guidance, so the SDK injects it into the agent's tool
- * catalog.
+ * Each field's description carries the bullet labels and reproducibility
+ * guidance, so the harness injects it into the agent's tool catalog.
  */
 
-import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { type TSchema, Type } from 'typebox';
+import { Value } from 'typebox/value';
+import { stringEnum } from './schema.js';
 
 // ============================================================================
 // CLASS DISCRIMINATOR
@@ -85,6 +85,7 @@ export type BlockedExploit = {
   vulnerability_id: string;
   title: string;
   vulnerable_location: string;
+  overview: string;
   prerequisites?: string | null;
   confidence: (typeof CONFIDENCE_VALUES)[number];
   current_blocker: string;
@@ -102,215 +103,181 @@ export type AddExploitInput = ExploitedExploit | BlockedExploit;
 // SCHEMA BUILDER
 // ============================================================================
 
-function buildSchemas(validIds: ReadonlySet<string>) {
-  const vulnerabilityIdField = z
-    .string()
-    .min(1)
-    .describe(
+export function buildSchemas(validIds: ReadonlySet<string>) {
+  const vulnerabilityIdField = Type.String({
+    minLength: 1,
+    description:
       'Vulnerability identifier (e.g. "INJ-VULN-03"). Must match an ID from this run\'s ' +
-        '{class}_exploitation_queue.json exactly — the collector rejects IDs not in the queue. ' +
-        `Valid IDs for this run: ${formatValidIdsPreview(validIds)}.`,
-    )
-    .refine((id: string) => validIds.has(id), {
-      message:
-        `Vulnerability ID not in this run's queue. Valid IDs: ` +
-        `${formatValidIdsPreview(validIds)}. ` +
-        'Check the queue.json for the canonical ID — likely a typo or hallucinated ID.',
-    });
+      '{class}_exploitation_queue.json exactly — the collector rejects IDs not in the queue. ' +
+      `Valid IDs for this run: ${formatValidIdsPreview(validIds)}.`,
+  });
 
-  const titleField = z
-    .string()
-    .min(1)
-    .describe(
+  const titleField = Type.String({
+    minLength: 1,
+    description:
       'Descriptive vulnerability title (e.g. "SQL Injection — User Search", "IDOR — Unauthorized ' +
-        'Access to User Orders"). Concise; encodes the vulnerability category and where it lives.',
-    );
+      'Access to User Orders"). Concise; encodes the vulnerability category and where it lives.',
+  });
 
-  const vulnerableLocationField = z
-    .string()
-    .min(1)
-    .describe(
-      'Endpoint or mechanism where the vulnerability exists (e.g. "GET /api/products?id=", ' +
-        '"POST /login", or a code location like "controllers/userController.js:42").',
-    );
+  const vulnerableLocationField = Type.String({
+    minLength: 1,
+    description:
+      'Endpoint or mechanism where the vulnerability exists (e.g. "GET /api/products?id=", ' + '"POST /login").',
+  });
 
-  const overviewField = z
-    .string()
-    .min(1)
-    .describe(
+  const overviewField = Type.String({
+    minLength: 1,
+    description:
       'Brief summary of the exploit itself — what the vulnerability is and how it was demonstrated ' +
-        '(or how it would be demonstrated, for blocked findings). 1-3 sentences.',
-    );
+      '(or how it would be demonstrated, for blocked findings). 1-3 sentences.',
+  });
 
-  const prerequisitesField = z
-    .string()
-    .nullable()
-    .optional()
-    .describe(
-      'Required setup, tools, or conditions to reproduce the exploit (e.g. authentication, ' +
+  const prerequisitesField = Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description:
+        'Required setup, tools, or conditions to reproduce the exploit (e.g. authentication, ' +
         'specific role, prior application state). Omit or pass null when no prerequisites apply.',
-    );
+    }),
+  );
 
-  const notesField = z
-    .string()
-    .nullable()
-    .optional()
-    .describe(
-      'Optional supplementary context — caveats, related findings, environmental observations. ' +
+  const notesField = Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description:
+        'Optional supplementary context — caveats, related findings, environmental observations. ' +
         'Free-form Markdown. Omit or pass null when N/A.',
-    );
+    }),
+  );
 
-  const statusField = z
-    .enum(['exploited', 'blocked'])
-    .describe(
+  const statusField = stringEnum(['exploited', 'blocked'], {
+    description:
       'Verdict bucket. Set to "exploited" only after reaching Proof of Exploitation Level 3+ with ' +
-        'concrete impact evidence (extracted data, executed JavaScript, account takeover, internal ' +
-        'service access). Set to "blocked" only for real vulnerabilities where external factors ' +
-        '(NOT security defenses) prevented full exploitation. Findings where a security defense ' +
-        'successfully prevented exploitation after exhaustive bypass attempts are FALSE POSITIVE — ' +
-        'route those to your workspace tracking file, not this tool.',
-    );
+      'concrete impact evidence (extracted data, executed JavaScript, account takeover, internal ' +
+      'service access). Set to "blocked" only for real vulnerabilities where external factors ' +
+      '(NOT security defenses) prevented full exploitation. Findings where a security defense ' +
+      'successfully prevented exploitation after exhaustive bypass attempts are FALSE POSITIVE — ' +
+      'route those to your workspace tracking file, not this tool.',
+  });
 
-  // Per-status fields. All optional at the SDK shape layer because a single
-  // ZodRawShape cannot express a top-level discriminated union; the handler
-  // re-validates against the discriminated union below for true enforcement.
-  const severityField = z
-    .enum(SEVERITY_VALUES)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="exploited". Severity of the demonstrated impact. Critical = Level 4 ' +
+  // Per-status fields. All optional at the flat shape layer because a single
+  // Type.Object cannot express a top-level discriminated union; the handler
+  // re-validates against the strict union below for true enforcement.
+  const severityField = Type.Optional(
+    Type.Union([stringEnum(SEVERITY_VALUES), Type.Null()], {
+      description:
+        'REQUIRED when status="exploited". Severity of the demonstrated impact. Critical = Level 4 ' +
         '(admin credentials extracted, sensitive data dumped, system commands executed, full account ' +
         'takeover). High = Level 3 (data extraction proven, authentication bypass confirmed, ' +
         'internal service access). Medium/Low based on impact narrowness or read-only access. Must ' +
         'reflect demonstrated impact, not theoretical potential.',
-    );
+    }),
+  );
 
-  const impactField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="exploited". Business/security impact achieved by the exploit ' +
+  const impactField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="exploited". Business/security impact achieved by the exploit ' +
         '(e.g. "Extracted full user table including bcrypt password hashes for 1,247 users", ' +
         '"Achieved RCE as the application user; arbitrary shell commands executed"). Must describe ' +
         'what was actually demonstrated, not what could theoretically happen.',
-    );
+    }),
+  );
 
-  const exploitationStepsField = z
-    .array(z.string().min(1))
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="exploited". Ordered, reproducible exploitation steps — one Markdown ' +
+  const exploitationStepsField = Type.Optional(
+    Type.Union([Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="exploited". Ordered, reproducible exploitation steps — one Markdown ' +
         'blob per numbered step. Each step must include full URLs (protocol + domain + port + path ' +
         '+ params), complete payloads, and copy-paste-ready commands. Use clear placeholders for ' +
         'variable values like [SESSION_TOKEN], [DATABASE_NAME], [TABLE_NAME], [TARGET_USER_ID]. ' +
         'Write each step as natural Markdown — interleave prose with fenced code blocks (```bash, ' +
         '```http, etc.) as you would in a write-up. Steps must be detailed enough that someone ' +
         'unfamiliar with the application can follow without additional research.',
-    );
+    }),
+  );
 
-  const proofOfImpactField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="exploited". Concrete evidence of successful exploitation — extracted ' +
+  const proofOfImpactField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="exploited". Concrete evidence of successful exploitation — extracted ' +
         'data, achieved actions, captured request/response pairs, log excerpts. Markdown blob; ' +
         'interleave prose with fenced code blocks. Must show what the exploit demonstrably achieved, ' +
         'not theoretical impact.',
-    );
+    }),
+  );
 
-  const confidenceField = z
-    .enum(CONFIDENCE_VALUES)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". Confidence that this finding is a real vulnerability that ' +
+  const confidenceField = Type.Optional(
+    Type.Union([stringEnum(CONFIDENCE_VALUES), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". Confidence that this finding is a real vulnerability that ' +
         'would be exploited if the external blocker were removed. High = code analysis strongly ' +
         'confirms vulnerability and partial exploitation (Level 1-2) succeeded. Medium = code ' +
         'analysis confirms but live evidence is partial. Low = signal-only; revisit if blocker is ' +
         'removed in a future run.',
-    );
+    }),
+  );
 
-  const currentBlockerField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". What prevents full exploitation (e.g. "Server crashes after ' +
+  const currentBlockerField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". What prevents full exploitation (e.g. "Server crashes after ' +
         '5 requests, blocking enumeration", "OAuth callback requires verified third-party email ' +
         'account we could not provision"). Must be an external operational constraint, not a ' +
         'security defense.',
-    );
+    }),
+  );
 
-  const potentialImpactField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". What could be achieved if the blocker were removed (e.g. ' +
+  const potentialImpactField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". What could be achieved if the blocker were removed (e.g. ' +
         '"Full database read access", "Account takeover of arbitrary user via reset-token leak"). ' +
         'Distinct from impact — this is the hypothetical outcome, not a demonstrated one.',
-    );
+    }),
+  );
 
-  const evidenceOfVulnerabilityField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". Code snippets, response excerpts, or observed behavior ' +
+  const evidenceOfVulnerabilityField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". Code snippets, response excerpts, or observed behavior ' +
         'proving the vulnerability is real. Markdown blob; interleave prose with fenced code blocks. ' +
         'This is what convinces the reader the finding is not a false positive despite incomplete ' +
         'exploitation.',
-    );
+    }),
+  );
 
-  const whatWeTriedField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". Log of attempted exploitation techniques and why each was ' +
+  const whatWeTriedField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". Log of attempted exploitation techniques and why each was ' +
         'blocked. Each attempt should document the payload, the observed result, and the inferred ' +
         'blocker. Markdown blob; multiple attempts as a list or distinct paragraphs. Demonstrates ' +
         'exhaustive bypass effort per the Bypass Exhaustion Protocol.',
-    );
+    }),
+  );
 
-  const howThisWouldBeExploitedField = z
-    .array(z.string().min(1))
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". Ordered hypothetical exploitation steps assuming the blocker ' +
+  const howThisWouldBeExploitedField = Type.Optional(
+    Type.Union([Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". Ordered hypothetical exploitation steps assuming the blocker ' +
         'is removed — one Markdown blob per numbered step. Same reproducibility requirements as ' +
         'exploitation_steps: full URLs, complete payloads, copy-paste-ready commands. Frame the ' +
         'first step as "If [blocker] were removed: …".',
-    );
+    }),
+  );
 
-  const expectedImpactField = z
-    .string()
-    .min(1)
-    .nullable()
-    .optional()
-    .describe(
-      'REQUIRED when status="blocked". Specific data or access that would be compromised if ' +
+  const expectedImpactField = Type.Optional(
+    Type.Union([Type.String({ minLength: 1 }), Type.Null()], {
+      description:
+        'REQUIRED when status="blocked". Specific data or access that would be compromised if ' +
         'exploitation succeeded (e.g. "Read access to all user profile data including PII; write ' +
         'access to user-owned resources"). Markdown blob.',
-    );
+    }),
+  );
 
-  // The flat shape passed to tool(). The SDK uses this to build the agent's
+  // The flat shape passed to defineTool. pi uses this to build the agent's
   // tool catalog. Per-status enforcement happens in the handler via the
-  // discriminated union below.
-  const flatShape = {
+  // strict union below.
+  const flatSchema = Type.Object({
     status: statusField,
     vulnerability_id: vulnerabilityIdField,
     title: titleField,
@@ -329,85 +296,83 @@ function buildSchemas(validIds: ReadonlySet<string>) {
     what_we_tried: whatWeTriedField,
     how_this_would_be_exploited: howThisWouldBeExploitedField,
     expected_impact: expectedImpactField,
-  };
+  });
 
   // Strict per-status validation. Re-runs in the handler so missing fields
-  // for the chosen status return a retryable Zod error to the agent.
-  const ExploitedSchema = z.object({
-    status: z.literal('exploited'),
+  // for the chosen status return a retryable error to the agent.
+  const ExploitedSchema = Type.Object({
+    status: Type.Literal('exploited'),
     vulnerability_id: vulnerabilityIdField,
     title: titleField,
     vulnerable_location: vulnerableLocationField,
     overview: overviewField,
     prerequisites: prerequisitesField,
-    severity: z.enum(SEVERITY_VALUES),
-    impact: z.string().min(1),
-    exploitation_steps: z.array(z.string().min(1)).min(1),
-    proof_of_impact: z.string().min(1),
+    severity: stringEnum(SEVERITY_VALUES),
+    impact: Type.String({ minLength: 1 }),
+    exploitation_steps: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    proof_of_impact: Type.String({ minLength: 1 }),
     notes: notesField,
   });
 
-  const BlockedSchema = z.object({
-    status: z.literal('blocked'),
+  const BlockedSchema = Type.Object({
+    status: Type.Literal('blocked'),
     vulnerability_id: vulnerabilityIdField,
     title: titleField,
     vulnerable_location: vulnerableLocationField,
+    overview: overviewField,
     prerequisites: prerequisitesField,
-    confidence: z.enum(CONFIDENCE_VALUES),
-    current_blocker: z.string().min(1),
-    potential_impact: z.string().min(1),
-    evidence_of_vulnerability: z.string().min(1),
-    what_we_tried: z.string().min(1),
-    how_this_would_be_exploited: z.array(z.string().min(1)).min(1),
-    expected_impact: z.string().min(1),
+    confidence: stringEnum(CONFIDENCE_VALUES),
+    current_blocker: Type.String({ minLength: 1 }),
+    potential_impact: Type.String({ minLength: 1 }),
+    evidence_of_vulnerability: Type.String({ minLength: 1 }),
+    what_we_tried: Type.String({ minLength: 1 }),
+    how_this_would_be_exploited: Type.Array(Type.String({ minLength: 1 }), { minItems: 1 }),
+    expected_impact: Type.String({ minLength: 1 }),
     notes: notesField,
   });
 
-  const StrictSchema = z.discriminatedUnion('status', [ExploitedSchema, BlockedSchema]);
+  const StrictSchema = Type.Union([ExploitedSchema, BlockedSchema]);
 
-  return { flatShape, StrictSchema };
+  return { flatSchema, StrictSchema };
 }
 
 // ============================================================================
 // RESPONSE HELPERS
 // ============================================================================
 
-interface ToolResult {
-  [x: string]: unknown;
-  content: Array<{ type: 'text'; text: string }>;
-  isError: boolean;
-}
-
-function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
+function toolResult(payload: Record<string, unknown>) {
   return {
-    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
-    isError: response.status === 'error',
+    content: [{ type: 'text' as const, text: JSON.stringify(payload, null, 2) }],
+    details: undefined,
   };
 }
 
-function successResult(data: Record<string, unknown>): ToolResult {
-  return createToolResult({ status: 'success', ...data });
+function successResult(data: Record<string, unknown>) {
+  return toolResult({ status: 'success', ...data });
 }
 
-function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
-  return createToolResult({ status: 'error', message, errorType, retryable });
+function errorResult(message: string, errorType = 'ValidationError', retryable = true) {
+  return toolResult({ status: 'error', message, errorType, retryable });
 }
 
-function formatZodIssues(error: z.ZodError): string {
-  return error.issues
-    .map((issue) => {
-      const path = issue.path.length > 0 ? issue.path.join('.') : '(root)';
-      return `- ${path}: ${issue.message}`;
-    })
-    .join('\n');
+function formatValueErrors(schema: TSchema, value: unknown): string {
+  const issues: string[] = [];
+  for (const err of Value.Errors(schema, value)) {
+    const path =
+      err.instancePath && err.instancePath.length > 0
+        ? err.instancePath.replace(/^\//, '').replace(/\//g, '.')
+        : '(root)';
+    issues.push(`- ${path}: ${err.message}`);
+  }
+  return issues.join('\n');
 }
 
 // ============================================================================
-// SERVER FACTORY
+// COLLECTOR FACTORY
 // ============================================================================
 
-export interface ExploitCollectorServer {
-  server: McpSdkServerConfigWithInstance;
+export interface ExploitCollector {
+  tools: ToolDefinition[];
   getAll(): AddExploitInput[];
 }
 
@@ -416,14 +381,16 @@ export interface CreateExploitCollectorOptions {
   validIds: ReadonlySet<string>;
 }
 
-export function createExploitCollector(options: CreateExploitCollectorOptions): ExploitCollectorServer {
+export function createExploitCollector(options: CreateExploitCollectorOptions): ExploitCollector {
   const { vulnClass, validIds } = options;
   const exploits: AddExploitInput[] = [];
-  const { flatShape, StrictSchema } = buildSchemas(validIds);
+  const { flatSchema, StrictSchema } = buildSchemas(validIds);
 
-  const addExploitTool = tool(
-    'add_exploit',
-    `Record a single processed ${vulnClass} vulnerability as structured exploitation evidence. ` +
+  const addExploitTool = defineTool({
+    name: 'add_exploit',
+    label: 'Add Exploit',
+    description:
+      `Record a single processed ${vulnClass} vulnerability as structured exploitation evidence. ` +
       'Call this once per vulnerability in your queue.json after reaching a definitive verdict ' +
       '(either successfully exploited or potential-but-blocked). The status field discriminates the ' +
       "two report buckets; required sub-fields differ per status (see each field's description for " +
@@ -432,20 +399,31 @@ export function createExploitCollector(options: CreateExploitCollectorOptions):
       'IDs. FALSE POSITIVE findings do NOT use this tool — they go to your workspace tracking file. ' +
       'After all queue vulnerabilities have been emitted, the host renderer assembles the ' +
       'deliverable Markdown from your recorded calls.',
-    flatShape,
-    async (input): Promise<ToolResult> => {
+    parameters: flatSchema,
+    async execute(_toolCallId, input) {
       // Re-validate against the strict discriminated union for per-status enforcement.
-      const parsed = StrictSchema.safeParse(input);
-      if (!parsed.success) {
+      if (!Value.Check(StrictSchema, input)) {
         return errorResult(
           `Schema validation failed for status="${(input as { status?: string }).status}". ` +
             'Required-field issues:\n' +
-            formatZodIssues(parsed.error),
+            formatValueErrors(StrictSchema, input),
           'ValidationError',
           true,
         );
       }
-      const typed = parsed.data as AddExploitInput;
+      const typed = Value.Clean(StrictSchema, structuredClone(input)) as AddExploitInput;
+
+      // Reject IDs not in this run's queue (typo'd or hallucinated).
+      if (!validIds.has(typed.vulnerability_id)) {
+        return errorResult(
+          `Vulnerability ID "${typed.vulnerability_id}" not in this run's queue. Valid IDs: ` +
+            `${formatValidIdsPreview(validIds)}. ` +
+            'Check the queue.json for the canonical ID — likely a typo or hallucinated ID.',
+          'ValidationError',
+          true,
+        );
+      }
+
       const existing = exploits.find((e) => e.vulnerability_id === typed.vulnerability_id);
       if (existing) {
         return errorResult(
@@ -458,16 +436,10 @@ export function createExploitCollector(options: CreateExploitCollectorOptions):
       exploits.push(typed);
       return successResult({ added: [typed.vulnerability_id], recorded_status: typed.status });
     },
-  );
-
-  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
-    name: 'exploit-collector',
-    version: '1.0.0',
-    tools: [addExploitTool],
   });
 
   return {
-    server,
+    tools: [addExploitTool],
     getAll: (): AddExploitInput[] => [...exploits],
   };
 }

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/collectors/pre-recon-collector.ts

@@ -0,0 +1,602 @@
+// 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.
+
+/**
+ * Pre-Recon Collector tools
+ *
+ * Exposes seven TypeBox-validated tools, one per section of the
+ * pre_recon_deliverable.md report. Every tool is one-shot (write-once;
+ * duplicate calls return DuplicateError). A skipped tool renders a placeholder
+ * rather than failing the activity. After the agent finishes, the host calls
+ * getAll() to harvest the typed payload bag, getCallStatus() to log the
+ * per-run call pattern, and runs the deterministic renderer to produce the
+ * deliverable Markdown.
+ *
+ * Each TypeBox schema's field-level descriptions carry the section guidance, so
+ * the harness injects it into the agent's tool catalog.
+ */
+
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { cleanInput } from './schema.js';
+
+// ============================================================================
+// SHARED SCHEMA
+// ============================================================================
+
+export const SinkRefSchema = Type.Object({
+  location: Type.String({
+    minLength: 1,
+    description:
+      'File path with line number (e.g., "templates/render.js:34") or richer prose ' +
+      '(e.g., "innerHTML at templates/render.js:34", "lines 45-67"). Must contain enough ' +
+      'detail for a downstream agent to find the exact location.',
+  }),
+  sink_function: Type.String({
+    minLength: 1,
+    description: 'The sink function or property name (e.g., "innerHTML", "axios.get", "eval", "document.write").',
+  }),
+  notes: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description:
+        'Optional context — render-context detail, attribute name, scope hints, or anything ' +
+        'a downstream agent needs to act on this sink. Omit when the location and sink_function ' +
+        'are sufficient on their own.',
+    }),
+  ),
+});
+
+export type SinkRef = Static<typeof SinkRefSchema>;
+
+// ============================================================================
+// PER-TOOL INPUT SCHEMAS
+// ============================================================================
+
+export const ExecutiveSummaryInputSchema = Type.Object({
+  text: Type.String({
+    minLength: 1,
+    description:
+      "Provide a 2-3 paragraph overview of the application's security posture, highlighting " +
+      'the most critical attack surfaces and architectural security decisions. Becomes ' +
+      'Section 1 of the rendered deliverable.',
+  }),
+});
+
+export const ApplicationIntelligenceInputSchema = Type.Object({
+  architecture: Type.Object(
+    {
+      framework_and_language: Type.String({
+        minLength: 1,
+        description: 'Framework and language details with their security implications.',
+      }),
+      architectural_pattern: Type.String({
+        minLength: 1,
+        description: 'Architectural pattern (monolith, microservices, hybrid) with trust boundary analysis.',
+      }),
+      critical_security_components: Type.String({
+        minLength: 1,
+        description: 'Critical security components with focus on auth, authz, and data protection.',
+      }),
+    },
+    {
+      description:
+        'Architecture & Technology Stack — driven by the Architecture Scanner sub-agent. ' +
+        'Becomes Section 2 of the rendered deliverable.',
+    },
+  ),
+  data_security: Type.Object(
+    {
+      database_security: Type.String({
+        minLength: 1,
+        description: 'Analyze encryption, access controls, and query safety in database interactions.',
+      }),
+      data_flow_security: Type.String({
+        minLength: 1,
+        description: 'Identify sensitive data paths and the protection mechanisms applied along them.',
+      }),
+      multi_tenant_isolation: Type.String({
+        minLength: 1,
+        description:
+          'Assess tenant separation effectiveness. If the application is single-tenant, state that ' +
+          'explicitly rather than leaving the field thin.',
+      }),
+    },
+    {
+      description:
+        'Data Security & Storage — driven by the Data Security Auditor sub-agent. ' +
+        'Becomes Section 4 of the rendered deliverable.',
+    },
+  ),
+  attack_surface: Type.Object(
+    {
+      external_entry_points: Type.String({
+        minLength: 1,
+        description: 'Detailed analysis of each public interface that is network-accessible.',
+      }),
+      internal_service_communication: Type.String({
+        minLength: 1,
+        description:
+          'Trust relationships and security assumptions between network-reachable services. ' +
+          'If the application is a single service with no internal RPC fabric, state that.',
+      }),
+      input_validation_patterns: Type.String({
+        minLength: 1,
+        description: 'How user input is handled and validated in network-accessible endpoints.',
+      }),
+      background_processing: Type.String({
+        minLength: 1,
+        description:
+          'Async job security and privilege models for jobs triggered by network requests. ' +
+          'If no async/background processing exists, state that.',
+      }),
+    },
+    {
+      description:
+        'Attack Surface Analysis — driven by Entry Point Mapper + Architecture Scanner sub-agents. ' +
+        'Only include entry points confirmed to be in-scope (network-reachable). ' +
+        'Becomes Section 5 of the rendered deliverable.',
+    },
+  ),
+  infrastructure: Type.Object(
+    {
+      secrets_management: Type.String({
+        minLength: 1,
+        description: 'How secrets are stored, rotated, and accessed.',
+      }),
+      configuration_security: Type.String({
+        minLength: 1,
+        description:
+          'Environment separation and secret handling. Specifically search for infrastructure ' +
+          'configuration (e.g., Nginx, Kubernetes Ingress, CDN settings) that defines security ' +
+          'headers like Strict-Transport-Security (HSTS) and Cache-Control, and report what was found.',
+      }),
+      external_dependencies: Type.String({
+        minLength: 1,
+        description: 'Third-party services and their security implications.',
+      }),
+      monitoring_and_logging: Type.String({
+        minLength: 1,
+        description: 'Security event visibility — what is logged, where it goes, and who can see it.',
+      }),
+    },
+    {
+      description: 'Infrastructure & Operational Security. Becomes Section 6 of the rendered deliverable.',
+    },
+  ),
+});
+
+export const AuthDeepDiveInputSchema = Type.Object({
+  authentication_mechanisms: Type.String({
+    minLength: 1,
+    description:
+      'Authentication mechanisms and their security properties. MUST include an exhaustive list of ' +
+      'all API endpoints used for authentication (e.g., login, logout, token refresh, password reset).',
+  }),
+  session_management: Type.String({
+    minLength: 1,
+    description:
+      'Session management and token security. Pinpoint the exact file and line(s) of code where ' +
+      'session cookie flags (HttpOnly, Secure, SameSite) are configured.',
+  }),
+  authz_model: Type.String({
+    minLength: 1,
+    description: 'Authorization model and potential bypass scenarios.',
+  }),
+  multi_tenancy: Type.String({
+    minLength: 1,
+    description: 'Multi-tenancy security implementation. If the application is single-tenant, state that explicitly.',
+  }),
+  sso_oauth_oidc: Type.Union([Type.String(), Type.Null()], {
+    description:
+      'SSO/OAuth/OIDC flows: identify the callback endpoints and locate the specific code that ' +
+      'validates the state and nonce parameters. Set null only if the application has no SSO/OAuth/OIDC ' +
+      'integration at all.',
+  }),
+});
+
+export const CodebaseIndexingInputSchema = Type.Object({
+  text: Type.String({
+    minLength: 1,
+    description:
+      "A detailed, multi-sentence paragraph describing the codebase's directory structure, " +
+      'organization, and significant tools or conventions used (e.g., build orchestration, code ' +
+      'generation, testing frameworks). Focus on how this structure impacts discoverability of ' +
+      'security-relevant components.',
+  }),
+});
+
+export const CriticalFilePathsInputSchema = Type.Object({
+  configuration: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'Configuration files (e.g., config/server.yaml, Dockerfile, docker-compose.yml).',
+  }),
+  authentication_and_authorization: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Auth/authz files (e.g., auth/jwt_middleware.go, internal/user/permissions.go, ' +
+      'config/initializers/session_store.rb, src/services/oauth_callback.js).',
+  }),
+  api_and_routing: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'API and routing files (e.g., cmd/api/main.go, internal/handlers/user_routes.go, ' +
+      'ts/graphql/schema.graphql).',
+  }),
+  data_models_and_db: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Data model and DB interaction files (e.g., db/migrations/001_initial.sql, ' +
+      'internal/models/user.go, internal/repository/sql_queries.go).',
+  }),
+  dependency_manifests: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'Dependency manifests (e.g., go.mod, package.json, requirements.txt).',
+  }),
+  sensitive_data_and_secrets: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Sensitive data and secrets handling (e.g., internal/utils/encryption.go, ' + 'internal/secrets/manager.go).',
+  }),
+  middleware_and_input_validation: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Middleware and input validation (e.g., internal/middleware/validator.go, ' +
+      'internal/handlers/input_parsers.go).',
+  }),
+  logging_and_monitoring: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'Logging and monitoring (e.g., internal/logging/logger.go, config/monitoring.yaml).',
+  }),
+  infrastructure_and_deployment: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Infrastructure and deployment (e.g., infra/pulumi/main.go, kubernetes/deploy.yaml, ' +
+      'nginx.conf, gateway-ingress.yaml).',
+  }),
+});
+
+export const XssSinksInputSchema = Type.Object({
+  applicable: Type.Boolean({
+    description:
+      'False only if the application has no web frontend at all. Otherwise true, even if no ' +
+      'sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
+  }),
+  html_body: Type.Array(SinkRefSchema, {
+    description:
+      'HTML Body Context sinks: element.innerHTML, element.outerHTML, document.write(), ' +
+      'document.writeln(), element.insertAdjacentHTML(), Range.createContextualFragment(), ' +
+      'and jQuery sinks like add(), after(), append(), before(), html(), prepend(), replaceWith(), wrap().',
+  }),
+  html_attribute: Type.Array(SinkRefSchema, {
+    description:
+      'HTML Attribute Context sinks: event handlers (onclick, onerror, onmouseover, onload, onfocus), ' +
+      'URL-based attributes (href, src, formaction, action, background, data), the style attribute, ' +
+      'iframe srcdoc, and general attributes (value, id, class, name, alt) when quotes are escaped.',
+  }),
+  javascript: Type.Array(SinkRefSchema, {
+    description:
+      'JavaScript Context sinks: eval(), Function() constructor, setTimeout() / setInterval() ' +
+      'with string arguments, and direct writes of user data into a <script> tag.',
+  }),
+  css: Type.Array(SinkRefSchema, {
+    description:
+      'CSS Context sinks: element.style properties (e.g., element.style.backgroundImage) and ' +
+      'direct writes of user data into a <style> tag.',
+  }),
+  url: Type.Array(SinkRefSchema, {
+    description:
+      'URL Context sinks: location / window.location, location.href, location.replace(), ' +
+      'location.assign(), window.open(), history.pushState(), history.replaceState(), ' +
+      'URL.createObjectURL(), and jQuery selector $(userInput) in older versions.',
+  }),
+});
+
+export const SsrfSinksInputSchema = Type.Object({
+  applicable: Type.Boolean({
+    description:
+      'False only if the application makes no outbound requests at all. Otherwise true, even if ' +
+      'no sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
+  }),
+  http_clients: Type.Array(SinkRefSchema, {
+    description:
+      'HTTP(S) clients: curl, requests (Python), axios (Node.js), fetch (JavaScript/Node.js), ' +
+      'net/http (Go), HttpClient (Java/.NET), urllib (Python), RestTemplate, WebClient, OkHttp, Apache HttpClient.',
+  }),
+  raw_sockets: Type.Array(SinkRefSchema, {
+    description:
+      'Raw sockets and connect APIs: Socket.connect, net.Dial (Go), socket.connect (Python), ' +
+      'TcpClient, UdpClient, NetworkStream, java.net.Socket, java.net.URL.openConnection().',
+  }),
+  url_openers: Type.Array(SinkRefSchema, {
+    description:
+      'URL openers and file includes: file_get_contents (PHP), fopen, include_once, require_once, ' +
+      'new URL().openStream() (Java), urllib.urlopen (Python), fs.readFile with URLs, ' +
+      'import() with dynamic URLs, loadHTML / loadXML with external sources.',
+  }),
+  redirect_handlers: Type.Array(SinkRefSchema, {
+    description:
+      'Redirect and "next URL" handlers: auto-follow redirects in HTTP clients, framework Location ' +
+      'handlers (response.redirect), URL validation in redirect chains, "Continue to" / "Return URL" parameters.',
+  }),
+  headless_browsers: Type.Array(SinkRefSchema, {
+    description:
+      'Headless browsers and render engines: Puppeteer (page.goto, page.setContent), ' +
+      'Playwright (page.navigate, page.route), Selenium WebDriver navigation, html-to-pdf converters ' +
+      '(wkhtmltopdf, Puppeteer PDF), and SSR with external content.',
+  }),
+  media_processors: Type.Array(SinkRefSchema, {
+    description:
+      'Media processors: ImageMagick (convert, identify with URLs), GraphicsMagick, FFmpeg with ' +
+      'network sources, wkhtmltopdf, Ghostscript with URL inputs, image optimization services with URL parameters.',
+  }),
+  link_preview: Type.Array(SinkRefSchema, {
+    description:
+      'Link preview and unfurlers: chat application link expanders, CMS link preview generators, ' +
+      'oEmbed endpoint fetchers, social media card generators, URL metadata extractors.',
+  }),
+  webhook_testers: Type.Array(SinkRefSchema, {
+    description:
+      'Webhook testers and callback verifiers: "ping my webhook" functionality, outbound callback ' +
+      'verification, health check notifications, event delivery confirmations, API endpoint validation tools.',
+  }),
+  sso_oidc_discovery: Type.Array(SinkRefSchema, {
+    description:
+      'SSO/OIDC discovery and JWKS fetchers: OpenID Connect discovery endpoints, JWKS fetchers, ' +
+      'OAuth authorization server metadata, SAML metadata fetchers, federation metadata retrievers.',
+  }),
+  importers: Type.Array(SinkRefSchema, {
+    description:
+      'Importers and data loaders: "import from URL" functionality, CSV/JSON/XML remote loaders, ' +
+      'RSS/Atom feed readers, API data synchronization, configuration file fetchers.',
+  }),
+  package_installers: Type.Array(SinkRefSchema, {
+    description:
+      'Package/plugin/theme installers: "install from URL" features, package managers with remote ' +
+      'sources, plugin/theme downloaders, update mechanisms with remote checks, dependency resolution ' +
+      'with external repos.',
+  }),
+  monitoring_and_health: Type.Array(SinkRefSchema, {
+    description:
+      'Monitoring and health check frameworks: URL pingers and uptime checkers, health check ' +
+      'endpoints, monitoring probe systems, alerting webhook senders, performance testing tools.',
+  }),
+  cloud_metadata: Type.Array(SinkRefSchema, {
+    description:
+      'Cloud metadata helpers: AWS/GCP/Azure instance metadata callers, cloud service discovery ' +
+      'mechanisms, container orchestration API clients, infrastructure metadata fetchers, service mesh ' +
+      'configuration retrievers.',
+  }),
+});
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type ExecutiveSummaryInput = Static<typeof ExecutiveSummaryInputSchema>;
+export type ApplicationIntelligenceInput = Static<typeof ApplicationIntelligenceInputSchema>;
+export type AuthDeepDiveInput = Static<typeof AuthDeepDiveInputSchema>;
+export type CodebaseIndexingInput = Static<typeof CodebaseIndexingInputSchema>;
+export type CriticalFilePathsInput = Static<typeof CriticalFilePathsInputSchema>;
+export type XssSinksInput = Static<typeof XssSinksInputSchema>;
+export type SsrfSinksInput = Static<typeof SsrfSinksInputSchema>;
+
+export interface PreReconData {
+  readonly executive_summary?: ExecutiveSummaryInput;
+  readonly application_intelligence?: ApplicationIntelligenceInput;
+  readonly auth_deep_dive?: AuthDeepDiveInput;
+  readonly codebase_indexing?: CodebaseIndexingInput;
+  readonly critical_file_paths?: CriticalFilePathsInput;
+  readonly xss_sinks?: XssSinksInput;
+  readonly ssrf_sinks?: SsrfSinksInput;
+}
+
+export const PRE_RECON_ONE_SHOT_TOOLS = [
+  'set_executive_summary',
+  'set_application_intelligence',
+  'set_auth_deep_dive',
+  'set_codebase_indexing',
+  'set_critical_file_paths',
+  'set_xss_sinks',
+  'set_ssrf_sinks',
+] as const;
+
+export type PreReconToolName = (typeof PRE_RECON_ONE_SHOT_TOOLS)[number];
+
+export type PreReconToolStatus = 'called' | 'skipped';
+
+export type PreReconCallStatus = Readonly<Record<PreReconToolName, PreReconToolStatus>>;
+
+// ============================================================================
+// 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
+// ============================================================================
+
+interface PreReconState {
+  executive_summary?: ExecutiveSummaryInput;
+  application_intelligence?: ApplicationIntelligenceInput;
+  auth_deep_dive?: AuthDeepDiveInput;
+  codebase_indexing?: CodebaseIndexingInput;
+  critical_file_paths?: CriticalFilePathsInput;
+  xss_sinks?: XssSinksInput;
+  ssrf_sinks?: SsrfSinksInput;
+}
+
+export interface PreReconCollector {
+  tools: ToolDefinition[];
+  getAll(): PreReconData;
+  getCallStatus(): PreReconCallStatus;
+}
+
+export function createPreReconCollector(): PreReconCollector {
+  const state: PreReconState = {};
+
+  function alreadyCalled(toolName: PreReconToolName) {
+    return errorResult(
+      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setExecutiveSummary = defineTool({
+    name: 'set_executive_summary',
+    label: 'Set Executive Summary',
+    description:
+      "Record the application's overall security posture as a short executive summary. " +
+      'Call exactly once before terminating. Becomes Section 1 of the rendered deliverable. ' +
+      'Duplicate calls are rejected.',
+    parameters: ExecutiveSummaryInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.executive_summary) return alreadyCalled('set_executive_summary');
+      state.executive_summary = cleanInput(ExecutiveSummaryInputSchema, input);
+      return successResult({ set: 'set_executive_summary' });
+    },
+  });
+
+  const setApplicationIntelligence = defineTool({
+    name: 'set_application_intelligence',
+    label: 'Set Application Intelligence',
+    description:
+      'Record the composite application intelligence — architecture, data security, attack surface, ' +
+      'and infrastructure — in a single call. Call exactly once before terminating. ' +
+      'Becomes Sections 2, 4, 5, and 6 of the rendered deliverable. Duplicate calls are rejected.',
+    parameters: ApplicationIntelligenceInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.application_intelligence) return alreadyCalled('set_application_intelligence');
+      state.application_intelligence = cleanInput(ApplicationIntelligenceInputSchema, input);
+      return successResult({ set: 'set_application_intelligence' });
+    },
+  });
+
+  const setAuthDeepDive = defineTool({
+    name: 'set_auth_deep_dive',
+    label: 'Set Auth Deep Dive',
+    description:
+      'Record the authentication & authorization deep dive. Call exactly once before terminating. ' +
+      'Becomes Section 3 of the rendered deliverable. Duplicate calls are rejected.',
+    parameters: AuthDeepDiveInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.auth_deep_dive) return alreadyCalled('set_auth_deep_dive');
+      state.auth_deep_dive = cleanInput(AuthDeepDiveInputSchema, input);
+      return successResult({ set: 'set_auth_deep_dive' });
+    },
+  });
+
+  const setCodebaseIndexing = defineTool({
+    name: 'set_codebase_indexing',
+    label: 'Set Codebase Indexing',
+    description:
+      'Record the overall codebase indexing narrative. Call exactly once before terminating. ' +
+      'Becomes Section 7 of the rendered deliverable. Duplicate calls are rejected.',
+    parameters: CodebaseIndexingInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.codebase_indexing) return alreadyCalled('set_codebase_indexing');
+      state.codebase_indexing = cleanInput(CodebaseIndexingInputSchema, input);
+      return successResult({ set: 'set_codebase_indexing' });
+    },
+  });
+
+  const setCriticalFilePaths = defineTool({
+    name: 'set_critical_file_paths',
+    label: 'Set Critical File Paths',
+    description:
+      'Record the catalog of critical file paths grouped by security relevance. Call exactly once ' +
+      'before terminating. Becomes Section 8 of the rendered deliverable. The next agent uses this ' +
+      'as a starting point for manual review. Duplicate calls are rejected.',
+    parameters: CriticalFilePathsInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.critical_file_paths) return alreadyCalled('set_critical_file_paths');
+      state.critical_file_paths = cleanInput(CriticalFilePathsInputSchema, input);
+      return successResult({ set: 'set_critical_file_paths' });
+    },
+  });
+
+  const setXssSinks = defineTool({
+    name: 'set_xss_sinks',
+    label: 'Set Xss Sinks',
+    description:
+      'Record discovered XSS sinks grouped by render context. Call exactly once before terminating. ' +
+      'If the application has no web frontend at all, set applicable=false; otherwise populate each ' +
+      'render-context array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
+      "the vuln-xss agent's testing todos downstream. Becomes Section 9 of the rendered deliverable. " +
+      'Duplicate calls are rejected.',
+    parameters: XssSinksInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.xss_sinks) return alreadyCalled('set_xss_sinks');
+      state.xss_sinks = cleanInput(XssSinksInputSchema, input);
+      return successResult({ set: 'set_xss_sinks' });
+    },
+  });
+
+  const setSsrfSinks = defineTool({
+    name: 'set_ssrf_sinks',
+    label: 'Set Ssrf Sinks',
+    description:
+      'Record discovered SSRF sinks grouped by sink category. Call exactly once before terminating. ' +
+      'If the application makes no outbound requests at all, set applicable=false; otherwise populate ' +
+      'each category array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
+      "the vuln-ssrf agent's testing todos downstream. Becomes Section 10 of the rendered deliverable. " +
+      'Duplicate calls are rejected.',
+    parameters: SsrfSinksInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.ssrf_sinks) return alreadyCalled('set_ssrf_sinks');
+      state.ssrf_sinks = cleanInput(SsrfSinksInputSchema, input);
+      return successResult({ set: 'set_ssrf_sinks' });
+    },
+  });
+
+  function statusOf<K extends PreReconToolName>(key: K): PreReconToolStatus {
+    const flagMap: Record<PreReconToolName, unknown> = {
+      set_executive_summary: state.executive_summary,
+      set_application_intelligence: state.application_intelligence,
+      set_auth_deep_dive: state.auth_deep_dive,
+      set_codebase_indexing: state.codebase_indexing,
+      set_critical_file_paths: state.critical_file_paths,
+      set_xss_sinks: state.xss_sinks,
+      set_ssrf_sinks: state.ssrf_sinks,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    tools: [
+      setExecutiveSummary,
+      setApplicationIntelligence,
+      setAuthDeepDive,
+      setCodebaseIndexing,
+      setCriticalFilePaths,
+      setXssSinks,
+      setSsrfSinks,
+    ],
+    getAll: (): PreReconData => ({
+      ...(state.executive_summary && { executive_summary: state.executive_summary }),
+      ...(state.application_intelligence && { application_intelligence: state.application_intelligence }),
+      ...(state.auth_deep_dive && { auth_deep_dive: state.auth_deep_dive }),
+      ...(state.codebase_indexing && { codebase_indexing: state.codebase_indexing }),
+      ...(state.critical_file_paths && { critical_file_paths: state.critical_file_paths }),
+      ...(state.xss_sinks && { xss_sinks: state.xss_sinks }),
+      ...(state.ssrf_sinks && { ssrf_sinks: state.ssrf_sinks }),
+    }),
+    getCallStatus: (): PreReconCallStatus => ({
+      set_executive_summary: statusOf('set_executive_summary'),
+      set_application_intelligence: statusOf('set_application_intelligence'),
+      set_auth_deep_dive: statusOf('set_auth_deep_dive'),
+      set_codebase_indexing: statusOf('set_codebase_indexing'),
+      set_critical_file_paths: statusOf('set_critical_file_paths'),
+      set_xss_sinks: statusOf('set_xss_sinks'),
+      set_ssrf_sinks: statusOf('set_ssrf_sinks'),
+    }),
+  };
+}

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

@@ -0,0 +1,876 @@
+// 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.
+
+/**
+ * Recon Collector tools
+ *
+ * Exposes nine TypeBox-validated tools that feed the recon_deliverable.md
+ * renderer — eight one-shot `set_*` tools, one per deliverable section, plus a
+ * multi-call `add_endpoints` tool that lets the agent split a large API
+ * inventory across calls (the only catalog whose realistic payload threatens
+ * the per-turn output cap).
+ *
+ * A skipped tool renders a "not provided" placeholder in that section rather
+ * than failing the activity. getCallStatus() exposes the per-run call pattern
+ * for logging. Each schema's field-level descriptions carry the section
+ * guidance, so pi injects it into the agent's tool catalog.
+ */
+
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { type Static, Type } from 'typebox';
+import { type SinkRef, SinkRefSchema } from './pre-recon-collector.js';
+import { cleanInput, stringEnum } from './schema.js';
+
+// ============================================================================
+// PER-TOOL INPUT SCHEMAS
+// ============================================================================
+
+export const ExecutiveSummaryInputSchema = Type.Object({
+  text: Type.String({
+    minLength: 1,
+    description:
+      "A brief overview of the application's purpose, core technology stack " +
+      '(e.g., Next.js, Cloudflare), and the primary user-facing components that ' +
+      'constitute the attack surface. Becomes Section 1 of the rendered deliverable.',
+  }),
+});
+
+export const TechnologyStackInputSchema = Type.Object({
+  frontend: Type.String({
+    minLength: 1,
+    description: 'Framework, key libraries, and authentication libraries used on the frontend.',
+  }),
+  backend: Type.String({
+    minLength: 1,
+    description: 'Language, framework, and key dependencies used on the backend.',
+  }),
+  infrastructure: Type.String({
+    minLength: 1,
+    description: 'Hosting provider, CDN, database type, and other infrastructure components.',
+  }),
+});
+
+export const AuthenticationInputSchema = Type.Object({
+  session_flow: Type.Object(
+    {
+      entry_points: Type.String({
+        minLength: 1,
+        description: 'Authentication entry points (e.g., /login, /register, /auth/sso).',
+      }),
+      mechanism: Type.String({
+        minLength: 1,
+        description:
+          'Describe the step-by-step authentication process: credential submission, token generation, ' +
+          'cookie setting, redirects, etc.',
+      }),
+      code_pointers: Type.String({
+        minLength: 1,
+        description:
+          'Pointers to the primary files and functions in the codebase that manage authentication and ' +
+          'session logic.',
+      }),
+    },
+    {
+      description:
+        'Authentication & Session Management Flow — overall entry points, mechanism, and code pointers. ' +
+        'Becomes Section 3 of the rendered deliverable.',
+    },
+  ),
+  role_assignment: Type.Object(
+    {
+      role_determination: Type.String({
+        minLength: 1,
+        description: 'How roles are assigned post-authentication — database lookup, JWT claims, external service, etc.',
+      }),
+      default_role: Type.String({
+        minLength: 1,
+        description: 'What role new users get by default.',
+      }),
+      role_upgrade_path: Type.String({
+        minLength: 1,
+        description:
+          'How users can gain higher privileges — admin approval, self-service, automatic, etc. ' +
+          'If no upgrade path exists, state that.',
+      }),
+      code_implementation: Type.String({
+        minLength: 1,
+        description: 'Where role assignment logic is implemented (file paths and functions).',
+      }),
+    },
+    {
+      description: 'Role Assignment Process — how roles are determined post-authentication. Becomes Section 3.1.',
+    },
+  ),
+  privilege_storage: Type.Object(
+    {
+      storage_location: Type.String({
+        minLength: 1,
+        description: 'Where user privileges are stored — JWT claims, session data, database, external service.',
+      }),
+      validation_points: Type.String({
+        minLength: 1,
+        description: 'Where role checks happen — middleware, decorators, inline checks.',
+      }),
+      cache_session_persistence: Type.String({
+        minLength: 1,
+        description: 'How long privileges are cached, and when they are refreshed.',
+      }),
+      code_pointers: Type.String({
+        minLength: 1,
+        description: 'Files that handle privilege validation.',
+      }),
+    },
+    {
+      description:
+        'Privilege Storage & Validation — where privileges live and where they are checked. ' + 'Becomes Section 3.2.',
+    },
+  ),
+  role_switching_impersonation: Type.Object(
+    {
+      applicable: Type.Boolean({
+        description:
+          'False only if the application has no impersonation, sudo-mode, or role-switching features ' +
+          'at all. When false, the other fields in this object may be null.',
+      }),
+      impersonation_features: Type.Union([Type.String(), Type.Null()], {
+        description:
+          'Any ability for admins or higher-privilege users to impersonate other users. Pass null when ' +
+          'applicable is false.',
+      }),
+      role_switching: Type.Union([Type.String(), Type.Null()], {
+        description: 'Temporary privilege elevation mechanisms like "sudo mode". Pass null when applicable is false.',
+      }),
+      audit_trail: Type.Union([Type.String(), Type.Null()], {
+        description:
+          'Whether role switches or impersonation events are logged, and where. Pass null when applicable is false.',
+      }),
+      code_implementation: Type.Union([Type.String(), Type.Null()], {
+        description:
+          'Where these features are implemented (file paths and functions). Pass null when applicable is false.',
+      }),
+    },
+    {
+      description:
+        'Role Switching & Impersonation — impersonation, sudo mode, audit trails. Becomes Section 3.3. ' +
+        'Set applicable=false if no such features exist; the other fields may be null in that case.',
+    },
+  ),
+});
+
+const HTTP_METHOD_VALUES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'WS'] as const;
+
+const EndpointSchema = Type.Object({
+  method: stringEnum(HTTP_METHOD_VALUES, {
+    description: 'HTTP method. Use WS for WebSocket upgrade endpoints.',
+  }),
+  path: Type.String({
+    minLength: 1,
+    description: 'Endpoint path with parameter placeholders, e.g. "/api/users/{user_id}".',
+  }),
+  required_role: Type.String({
+    minLength: 1,
+    description: 'Minimum role needed (anon, user, admin, etc.).',
+  }),
+  object_id_parameters: Type.Array(Type.String(), {
+    description: 'Parameters that identify specific objects (user_id, order_id, etc.). Empty array if none.',
+  }),
+  authorization_mechanism: Type.String({
+    minLength: 1,
+    description:
+      'How access is controlled — middleware, decorator, inline check. ' +
+      'E.g. "Bearer Token + ownership check", "requireAuth() + requireAdmin()", "None".',
+  }),
+  description: Type.String({
+    minLength: 1,
+    description: "Brief description of the endpoint's purpose.",
+  }),
+  code_pointer: Type.String({
+    minLength: 1,
+    description: 'File path and (where possible) line number of the handler. E.g. "auth.controller.ts:45".',
+  }),
+});
+
+export const AddEndpointsInputSchema = Type.Object({
+  endpoints: Type.Array(EndpointSchema, {
+    description:
+      'A batch of network-accessible API endpoints to append to the catalog. Include only endpoints ' +
+      'reachable through the deployed application — exclude CLI tools, dev-only routes, build scripts. ' +
+      'Duplicate (method, path) pairs across calls are skipped as no-ops; the response reports which ' +
+      'were added vs. skipped.',
+  }),
+});
+
+export const InputVectorsInputSchema = Type.Object({
+  url_parameters: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'URL parameter input vectors — each entry should identify the parameter and (where possible) ' +
+      'the file:line of the handler. E.g. "?redirect_url= @ auth.controller.ts:88".',
+  }),
+  post_body_fields: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'POST/PUT body field input vectors (JSON or form). E.g. "username @ login.handler.ts:34", ' +
+      '"profile.description @ users.controller.ts:120".',
+  }),
+  http_headers: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'HTTP header input vectors. Include both standard headers consumed by app code (e.g., ' +
+      'X-Forwarded-For) and custom application headers.',
+  }),
+  cookie_values: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'Cookie-based input vectors. E.g. "preferences_cookie @ middleware/prefs.ts:22".',
+  }),
+});
+
+const ENTITY_TYPE_VALUES = ['ExternAsset', 'Service', 'Identity', 'DataStore', 'AdminPlane', 'ThirdParty'] as const;
+
+const ENTITY_ZONE_VALUES = ['Internet', 'Edge', 'App', 'Data', 'Admin', 'BuildCI', 'ThirdParty'] as const;
+
+const DATA_LABEL_VALUES = ['PII', 'Tokens', 'Payments', 'Secrets', 'Public'] as const;
+
+const FLOW_CHANNEL_VALUES = ['HTTP', 'HTTPS', 'TCP', 'Message', 'File', 'Token'] as const;
+
+const GUARD_CATEGORY_VALUES = [
+  'Auth',
+  'Network',
+  'Protocol',
+  'Env',
+  'RateLimit',
+  'Authorization',
+  'ObjectOwnership',
+] as const;
+
+const EntityMetadataPairSchema = Type.Object({
+  key: Type.String({
+    minLength: 1,
+    description: 'Metadata key (e.g., "Hosts", "Endpoints", "Engine", "Issuer").',
+  }),
+  value: Type.String({
+    minLength: 1,
+    description: 'Metadata value for this key.',
+  }),
+});
+
+const EntitySchema = Type.Object({
+  title: Type.String({
+    minLength: 1,
+    description: 'Unique short name for the entity (e.g., "ExampleWebApp", "PostgreSQL-DB", "IdentityProvider").',
+  }),
+  type: stringEnum(ENTITY_TYPE_VALUES, {
+    description:
+      'Entity type. ExternAsset = client-side asset; Service = backend service; Identity = identity ' +
+      'provider; DataStore = database / cache / object store; AdminPlane = admin/control surface; ' +
+      'ThirdParty = external integration.',
+  }),
+  zone: stringEnum(ENTITY_ZONE_VALUES, {
+    description:
+      'Trust zone. Internet = public; Edge = CDN/WAF/reverse-proxy tier; App = application/business logic; ' +
+      'Data = persistent storage; Admin = administrative surface; BuildCI = build/CI/CD infrastructure; ' +
+      'ThirdParty = external trust domain.',
+  }),
+  tech: Type.String({
+    minLength: 1,
+    description: 'Short technology/framework description (e.g., "Node/Express", "Postgres 14", "AWS S3").',
+  }),
+  data: Type.Array(stringEnum(DATA_LABEL_VALUES), {
+    description: 'Data labels handled by this entity. Empty array if the entity handles only Public data.',
+  }),
+  notes: Type.String({
+    description: 'Freeform context (e.g., "public-facing", "stores sensitive user data"). Empty string if none.',
+  }),
+  metadata: Type.Array(EntityMetadataPairSchema, {
+    description:
+      'Ordered key/value pairs of technical metadata for this entity. Becomes the Section 6.2 row ' +
+      'rendered as "Key: Value; Key: Value; …". Example pairs for a service: Hosts, Endpoints, Auth, ' +
+      'Dependencies; for a datastore: Engine, Exposure, Consumers, Credentials.',
+  }),
+});
+
+const FlowSchema = Type.Object({
+  from: Type.String({
+    minLength: 1,
+    description: 'Source entity title — must match a title from the entities array.',
+  }),
+  to: Type.String({
+    minLength: 1,
+    description: 'Destination entity title — must match a title from the entities array.',
+  }),
+  channel: stringEnum(FLOW_CHANNEL_VALUES, { description: 'Transport channel for this flow.' }),
+  path_port: Type.String({
+    minLength: 1,
+    description: 'Path and/or port for this flow. E.g. ":443 /api/users/me", ":5432", "queue: orders".',
+  }),
+  guards: Type.Array(Type.String({ minLength: 1 }), {
+    description:
+      'Guard names that gate this flow. Each should match a name from the guards array. Empty array ' +
+      'means no guards apply (publicly accessible).',
+  }),
+  touches: Type.Array(stringEnum(DATA_LABEL_VALUES), {
+    description: 'Data labels this flow carries. Empty array if only Public data flows.',
+  }),
+});
+
+const GuardSchema = Type.Object({
+  name: Type.String({
+    minLength: 1,
+    description: 'Short guard identifier (e.g., "auth:user", "ownership:user", "vpc-only", "mtls").',
+  }),
+  category: stringEnum(GUARD_CATEGORY_VALUES, {
+    description:
+      'Guard category. Auth = authentication identity; Authorization = role/scope check; ' +
+      'ObjectOwnership = ownership-based check; Network = network-level restriction; ' +
+      'Protocol = protocol-level requirement; Env = environment-bound restriction; ' +
+      'RateLimit = throttling.',
+  }),
+  statement: Type.String({
+    minLength: 1,
+    description: 'One-sentence description of what this guard enforces.',
+  }),
+});
+
+export const NetworkMapInputSchema = Type.Object({
+  entities: Type.Array(EntitySchema, {
+    description:
+      'All major components of the system. Becomes Section 6.1 (Entities) and Section 6.2 ' +
+      '(Entity Metadata, split per-entity from the metadata field).',
+  }),
+  flows: Type.Array(FlowSchema, {
+    description:
+      'How entities communicate. Becomes Section 6.3. The from/to fields cross-reference entities ' +
+      'by title; the guards field cross-references guards by name.',
+  }),
+  guards: Type.Array(GuardSchema, {
+    description: 'Catalog of guards referenced by flows. Becomes Section 6.4.',
+  }),
+});
+
+const RoleSchema = Type.Object({
+  name: Type.String({
+    minLength: 1,
+    description: 'Role name (e.g., "anon", "user", "admin", "team_admin").',
+  }),
+  privilege_level: Type.Integer({
+    minimum: 0,
+    maximum: 10,
+    description: 'Privilege rank from 0 (lowest, anonymous) to 10 (highest, full admin).',
+  }),
+  scope_domain: Type.String({
+    minLength: 1,
+    description: 'Scope of this role: Global, Org, Team, Project, etc.',
+  }),
+  code_implementation: Type.String({
+    minLength: 1,
+    description: 'Where this role is defined or checked (middleware, decorator, file:line, etc.).',
+  }),
+  default_landing_page: Type.String({
+    minLength: 1,
+    description: 'Default landing page or route after authentication. Use "N/A" for roles without a UI.',
+  }),
+  accessible_route_patterns: Type.Array(Type.String({ minLength: 1 }), {
+    description: 'Route patterns this role can access. Empty array if the role has no UI access.',
+  }),
+  authentication_method: Type.String({
+    minLength: 1,
+    description: 'How this role authenticates: "None" (anon), "Session/JWT", "Session/JWT + role claim", etc.',
+  }),
+  middleware_guards: Type.String({
+    minLength: 1,
+    description: 'Middleware and guards that enforce this role (e.g., "requireAuth() + requireAdmin()").',
+  }),
+  permission_checks: Type.String({
+    minLength: 1,
+    description: 'How permission checks are expressed in code (e.g., "req.user.role === \'admin\'").',
+  }),
+  storage_location: Type.String({
+    minLength: 1,
+    description: 'Where this role is stored at runtime (JWT claims, session data, etc.).',
+  }),
+});
+
+const PrivilegeLatticeSchema = Type.Object({
+  ordering_diagram: Type.String({
+    minLength: 1,
+    description:
+      'ASCII diagram showing role ordering. Use → for "can access resources of". ' + 'E.g. "anon → user → admin".',
+  }),
+  parallel_isolation_notes: Type.String({
+    description:
+      'Notes on parallel isolation between roles using ||. E.g. "team_admin || dept_admin (both > user, ' +
+      'but isolated from each other)". Empty string if no parallel isolation exists.',
+  }),
+  role_switching_notes: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description:
+        'Optional pointer to impersonation, sudo mode, or role-switching mechanisms documented in ' +
+        'set_authentication.role_switching_impersonation. Null/omitted if no such mechanisms exist.',
+    }),
+  ),
+});
+
+export const RoleArchitectureInputSchema = Type.Object({
+  roles: Type.Array(RoleSchema, {
+    description:
+      'All distinct privilege levels found in the application. Becomes Sections 7.1 (Discovered Roles), ' +
+      '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping), split by the renderer per-role.',
+  }),
+  privilege_lattice: Type.Object(PrivilegeLatticeSchema.properties, {
+    description: 'The role hierarchy showing dominance and parallel isolation. Becomes Section 7.2.',
+  }),
+});
+
+const PRIORITY_VALUES = ['High', 'Medium', 'Low'] as const;
+
+const HorizontalCandidateSchema = Type.Object({
+  priority: stringEnum(PRIORITY_VALUES, {
+    description: 'Priority: High, Medium, or Low, based on data sensitivity (title-case literals).',
+  }),
+  endpoint_pattern: Type.String({
+    minLength: 1,
+    description: 'Endpoint pattern with the object identifier. E.g. "/api/orders/{order_id}".',
+  }),
+  object_id_parameter: Type.String({
+    minLength: 1,
+    description: 'The parameter name that identifies the target object (e.g., "order_id", "user_id").',
+  }),
+  data_type: Type.String({
+    minLength: 1,
+    description: 'Type of data exposed: user_data, financial, admin_config, user_files, etc.',
+  }),
+  sensitivity: Type.String({
+    minLength: 1,
+    description: 'One-line description of what is at risk (e.g., "User can access other users\' orders").',
+  }),
+});
+
+const VerticalCandidateSchema = Type.Object({
+  target_role: Type.String({
+    minLength: 1,
+    description: 'Role required to access this endpoint (the role being escalated to).',
+  }),
+  endpoint_pattern: Type.String({
+    minLength: 1,
+    description: 'Endpoint pattern that requires elevated privileges. E.g. "/admin/*", "/api/admin/users".',
+  }),
+  functionality: Type.String({
+    minLength: 1,
+    description: 'What the endpoint does (e.g., "Administrative functions", "User management").',
+  }),
+  risk_level: stringEnum(PRIORITY_VALUES, {
+    description: 'Risk level: High, Medium, or Low (title-case literals).',
+  }),
+});
+
+const ContextCandidateSchema = Type.Object({
+  workflow: Type.String({
+    minLength: 1,
+    description: 'Multi-step workflow name (e.g., "Checkout", "Onboarding", "Password Reset").',
+  }),
+  endpoint: Type.String({
+    minLength: 1,
+    description: 'Endpoint that assumes a prior workflow state. E.g. "/api/checkout/confirm".',
+  }),
+  expected_prior_state: Type.String({
+    minLength: 1,
+    description: 'What state should already exist before this endpoint is called.',
+  }),
+  bypass_potential: Type.String({
+    minLength: 1,
+    description: 'What an attacker could achieve by skipping the prior state.',
+  }),
+});
+
+export const AuthzCandidatesInputSchema = Type.Object({
+  horizontal: Type.Array(HorizontalCandidateSchema, {
+    description:
+      "Endpoints with object identifiers that could allow horizontal access to other users' " +
+      'resources. Becomes Section 8.1. The renderer assigns stable AUTHZ-CAND-NN IDs.',
+  }),
+  vertical: Type.Array(VerticalCandidateSchema, {
+    description:
+      'Endpoints that require higher privileges and could be targets for vertical escalation. ' +
+      'Becomes Section 8.2. Exclude endpoints intentionally shared across roles.',
+  }),
+  context: Type.Array(ContextCandidateSchema, {
+    description: 'Multi-step workflow endpoints that assume prior steps were completed. Becomes Section 8.3.',
+  }),
+});
+
+export const InjectionSourcesInputSchema = Type.Object({
+  applicable: Type.Boolean({
+    description:
+      'False only if the application has no network-accessible code paths reaching dangerous sinks ' +
+      'at all. Otherwise true, even if no sources were found in a given category — empty arrays mean ' +
+      '"scanned this category, no sources found".',
+  }),
+  command_injection: Type.Array(SinkRefSchema, {
+    description:
+      'Command injection sources: data flowing from a user-controlled origin into a program variable ' +
+      'that is eventually interpolated into a shell or system command string (within network-accessible ' +
+      'code paths).',
+  }),
+  sql_injection: Type.Array(SinkRefSchema, {
+    description:
+      'SQL injection sources: user-controllable input that reaches a database query string (within ' +
+      'network-accessible code paths).',
+  }),
+  lfi_rfi: Type.Array(SinkRefSchema, {
+    description:
+      'Local/Remote File Inclusion sources: user-controllable input passed to include/require/load ' +
+      'functions that resolve to filesystem or remote paths (within network-accessible code paths).',
+  }),
+  path_traversal: Type.Array(SinkRefSchema, {
+    description:
+      'Path traversal sources: user-controllable input that influences file paths in read/write ' +
+      'operations (fopen, readFile, etc.) within network-accessible code paths.',
+  }),
+  ssti: Type.Array(SinkRefSchema, {
+    description:
+      'Server-Side Template Injection sources: user-controllable input embedded in template ' +
+      'expressions or template content within network-accessible code paths.',
+  }),
+  deserialization: Type.Array(SinkRefSchema, {
+    description:
+      'Insecure deserialization sources: user-controllable input passed to deserialization functions ' +
+      'within network-accessible code paths.',
+  }),
+});
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type ExecutiveSummaryInput = Static<typeof ExecutiveSummaryInputSchema>;
+export type TechnologyStackInput = Static<typeof TechnologyStackInputSchema>;
+export type AuthenticationInput = Static<typeof AuthenticationInputSchema>;
+export type AddEndpointsInput = Static<typeof AddEndpointsInputSchema>;
+export type Endpoint = Static<typeof EndpointSchema>;
+export type InputVectorsInput = Static<typeof InputVectorsInputSchema>;
+export type NetworkMapInput = Static<typeof NetworkMapInputSchema>;
+export type Entity = Static<typeof EntitySchema>;
+export type Flow = Static<typeof FlowSchema>;
+export type Guard = Static<typeof GuardSchema>;
+export type RoleArchitectureInput = Static<typeof RoleArchitectureInputSchema>;
+export type Role = Static<typeof RoleSchema>;
+export type PrivilegeLattice = Static<typeof PrivilegeLatticeSchema>;
+export type AuthzCandidatesInput = Static<typeof AuthzCandidatesInputSchema>;
+export type HorizontalCandidate = Static<typeof HorizontalCandidateSchema>;
+export type VerticalCandidate = Static<typeof VerticalCandidateSchema>;
+export type ContextCandidate = Static<typeof ContextCandidateSchema>;
+export type InjectionSourcesInput = Static<typeof InjectionSourcesInputSchema>;
+export type Priority = (typeof PRIORITY_VALUES)[number];
+
+export interface ReconData {
+  readonly executive_summary?: ExecutiveSummaryInput;
+  readonly technology_stack?: TechnologyStackInput;
+  readonly authentication?: AuthenticationInput;
+  readonly endpoints?: readonly Endpoint[];
+  readonly input_vectors?: InputVectorsInput;
+  readonly network_map?: NetworkMapInput;
+  readonly role_architecture?: RoleArchitectureInput;
+  readonly authz_candidates?: AuthzCandidatesInput;
+  readonly injection_sources?: InjectionSourcesInput;
+}
+
+export const RECON_ONE_SHOT_TOOLS = [
+  'set_executive_summary',
+  'set_technology_stack',
+  'set_authentication',
+  'set_input_vectors',
+  'set_network_map',
+  'set_role_architecture',
+  'set_authz_candidates',
+  'set_injection_sources',
+] as const;
+
+export type ReconOneShotToolName = (typeof RECON_ONE_SHOT_TOOLS)[number];
+
+export type ReconToolStatus = 'called' | 'skipped';
+
+export interface ReconCallStatus {
+  readonly set_executive_summary: ReconToolStatus;
+  readonly set_technology_stack: ReconToolStatus;
+  readonly set_authentication: ReconToolStatus;
+  readonly add_endpoints: { readonly calls: number; readonly endpoints_seen: number };
+  readonly set_input_vectors: ReconToolStatus;
+  readonly set_network_map: ReconToolStatus;
+  readonly set_role_architecture: ReconToolStatus;
+  readonly set_authz_candidates: ReconToolStatus;
+  readonly set_injection_sources: ReconToolStatus;
+}
+
+// ============================================================================
+// 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 });
+}
+
+function endpointKey(method: string, path: string): string {
+  return `${method} ${path}`;
+}
+
+// ============================================================================
+// COLLECTOR FACTORY
+// ============================================================================
+
+interface ReconState {
+  executive_summary?: ExecutiveSummaryInput;
+  technology_stack?: TechnologyStackInput;
+  authentication?: AuthenticationInput;
+  input_vectors?: InputVectorsInput;
+  network_map?: NetworkMapInput;
+  role_architecture?: RoleArchitectureInput;
+  authz_candidates?: AuthzCandidatesInput;
+  injection_sources?: InjectionSourcesInput;
+}
+
+export interface ReconCollector {
+  tools: ToolDefinition[];
+  getAll(): ReconData;
+  getCallStatus(): ReconCallStatus;
+}
+
+export function createReconCollector(): ReconCollector {
+  const state: ReconState = {};
+
+  const endpoints: Endpoint[] = [];
+  const seenEndpointKeys = new Set<string>();
+  let addEndpointsCalls = 0;
+
+  function alreadyCalled(toolName: ReconOneShotToolName) {
+    return errorResult(
+      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setExecutiveSummary = defineTool({
+    name: 'set_executive_summary',
+    label: 'Set Executive Summary',
+    description:
+      "Record the application's executive summary: purpose, core technology stack, and primary " +
+      'user-facing components. Call exactly once before terminating. Becomes Section 1 of the rendered ' +
+      'deliverable. Duplicate calls are rejected.',
+    parameters: ExecutiveSummaryInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.executive_summary) return alreadyCalled('set_executive_summary');
+      state.executive_summary = cleanInput(ExecutiveSummaryInputSchema, input);
+      return successResult({ set: 'set_executive_summary' });
+    },
+  });
+
+  const setTechnologyStack = defineTool({
+    name: 'set_technology_stack',
+    label: 'Set Technology Stack',
+    description:
+      'Record the technology and service map: frontend, backend, and infrastructure. Call exactly once ' +
+      'before terminating. Becomes Section 2 of the rendered deliverable. Duplicate calls are rejected.',
+    parameters: TechnologyStackInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.technology_stack) return alreadyCalled('set_technology_stack');
+      state.technology_stack = cleanInput(TechnologyStackInputSchema, input);
+      return successResult({ set: 'set_technology_stack' });
+    },
+  });
+
+  const setAuthentication = defineTool({
+    name: 'set_authentication',
+    label: 'Set Authentication',
+    description:
+      'Record the authentication and session management architecture: session flow, role assignment, ' +
+      'privilege storage, and role switching/impersonation. Call exactly once before terminating. ' +
+      'Becomes Sections 3, 3.1, 3.2, and 3.3 of the rendered deliverable. Set ' +
+      'role_switching_impersonation.applicable=false (with the other fields null) if no such features ' +
+      'exist. Duplicate calls are rejected.',
+    parameters: AuthenticationInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.authentication) return alreadyCalled('set_authentication');
+      state.authentication = cleanInput(AuthenticationInputSchema, input);
+      return successResult({ set: 'set_authentication' });
+    },
+  });
+
+  const addEndpoints = defineTool({
+    name: 'add_endpoints',
+    label: 'Add Endpoints',
+    description:
+      'Append a batch of network-accessible API endpoints to the catalog. May be called multiple times — ' +
+      'each call appends. Use a single call for small inventories, or split across 2-3 calls for large ' +
+      'inventories (50+ endpoints) to keep individual payloads comfortable. Duplicate (method, path) ' +
+      'pairs across calls are skipped as no-ops; the response reports added vs. skipped. Becomes ' +
+      'Section 4 of the rendered deliverable and drives vuln-authz / vuln-injection todos downstream. ' +
+      'The renderer sorts by (path, method) before rendering, so emission order does not affect output.',
+    parameters: AddEndpointsInputSchema,
+    async execute(_toolCallId, input) {
+      addEndpointsCalls += 1;
+      const added: string[] = [];
+      const skipped: string[] = [];
+      for (const ep of input.endpoints) {
+        const key = endpointKey(ep.method, ep.path);
+        if (seenEndpointKeys.has(key)) {
+          skipped.push(key);
+          continue;
+        }
+        seenEndpointKeys.add(key);
+        endpoints.push(cleanInput(EndpointSchema, ep));
+        added.push(key);
+      }
+      return successResult({
+        set: 'add_endpoints',
+        added: added.length,
+        duplicates_skipped: skipped,
+        total_accumulated: endpoints.length,
+      });
+    },
+  });
+
+  const setInputVectors = defineTool({
+    name: 'set_input_vectors',
+    label: 'Set Input Vectors',
+    description:
+      'Record potential input vectors grouped by source: URL parameters, POST body fields, HTTP headers, ' +
+      'and cookie values. Call exactly once before terminating. Becomes Section 5 of the rendered ' +
+      'deliverable. Drives downstream vulnerability analysis. Duplicate calls are rejected.',
+    parameters: InputVectorsInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.input_vectors) return alreadyCalled('set_input_vectors');
+      state.input_vectors = cleanInput(InputVectorsInputSchema, input);
+      return successResult({ set: 'set_input_vectors' });
+    },
+  });
+
+  const setNetworkMap = defineTool({
+    name: 'set_network_map',
+    label: 'Set Network Map',
+    description:
+      'Record the network and interaction map: entities, flows, and guards. Call exactly once before ' +
+      'terminating. Becomes Sections 6.1 (Entities), 6.2 (Entity Metadata), 6.3 (Flows), and 6.4 ' +
+      '(Guards Directory) of the rendered deliverable. The renderer splits the entities array into ' +
+      'the 6.1 and 6.2 tables and sorts each array deterministically. Duplicate calls are rejected.',
+    parameters: NetworkMapInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.network_map) return alreadyCalled('set_network_map');
+      state.network_map = cleanInput(NetworkMapInputSchema, input);
+      return successResult({ set: 'set_network_map' });
+    },
+  });
+
+  const setRoleArchitecture = defineTool({
+    name: 'set_role_architecture',
+    label: 'Set Role Architecture',
+    description:
+      'Record the role and privilege architecture: discovered roles and the privilege lattice. Call ' +
+      'exactly once before terminating. Becomes Sections 7.1 (Discovered Roles), 7.2 (Privilege Lattice), ' +
+      '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping) of the rendered deliverable. The renderer ' +
+      'splits the roles array into the per-section tables. Duplicate calls are rejected.',
+    parameters: RoleArchitectureInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.role_architecture) return alreadyCalled('set_role_architecture');
+      state.role_architecture = cleanInput(RoleArchitectureInputSchema, input);
+      return successResult({ set: 'set_role_architecture' });
+    },
+  });
+
+  const setAuthzCandidates = defineTool({
+    name: 'set_authz_candidates',
+    label: 'Set Authz Candidates',
+    description:
+      'Record authorization vulnerability candidates: horizontal escalation, vertical escalation, and ' +
+      'context-based candidates. Call exactly once before terminating. Becomes Sections 8.1, 8.2, and ' +
+      '8.3 of the rendered deliverable. The renderer assigns stable AUTHZ-CAND-NN IDs across the three ' +
+      'sub-arrays in horizontal → vertical → context order, which vuln-authz reads as its todo list. ' +
+      'Duplicate calls are rejected.',
+    parameters: AuthzCandidatesInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.authz_candidates) return alreadyCalled('set_authz_candidates');
+      state.authz_candidates = cleanInput(AuthzCandidatesInputSchema, input);
+      return successResult({ set: 'set_authz_candidates' });
+    },
+  });
+
+  const setInjectionSources = defineTool({
+    name: 'set_injection_sources',
+    label: 'Set Injection Sources',
+    description:
+      'Record discovered injection sources grouped by vulnerability class. Call exactly once before ' +
+      'terminating. If the application has no network-accessible code paths to dangerous sinks, set ' +
+      'applicable=false; otherwise populate each category array (empty arrays mean "scanned, no sources ' +
+      'of this kind"). Becomes Section 9 of the rendered deliverable. Drives the vuln-injection agent\'s ' +
+      'todos downstream. Duplicate calls are rejected.',
+    parameters: InjectionSourcesInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.injection_sources) return alreadyCalled('set_injection_sources');
+      state.injection_sources = cleanInput(InjectionSourcesInputSchema, input);
+      return successResult({ set: 'set_injection_sources' });
+    },
+  });
+
+  function statusOf<K extends ReconOneShotToolName>(key: K): ReconToolStatus {
+    const flagMap: Record<ReconOneShotToolName, unknown> = {
+      set_executive_summary: state.executive_summary,
+      set_technology_stack: state.technology_stack,
+      set_authentication: state.authentication,
+      set_input_vectors: state.input_vectors,
+      set_network_map: state.network_map,
+      set_role_architecture: state.role_architecture,
+      set_authz_candidates: state.authz_candidates,
+      set_injection_sources: state.injection_sources,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    tools: [
+      setExecutiveSummary,
+      setTechnologyStack,
+      setAuthentication,
+      addEndpoints,
+      setInputVectors,
+      setNetworkMap,
+      setRoleArchitecture,
+      setAuthzCandidates,
+      setInjectionSources,
+    ],
+    getAll: (): ReconData => ({
+      ...(state.executive_summary && { executive_summary: state.executive_summary }),
+      ...(state.technology_stack && { technology_stack: state.technology_stack }),
+      ...(state.authentication && { authentication: state.authentication }),
+      ...(endpoints.length > 0 && { endpoints }),
+      ...(state.input_vectors && { input_vectors: state.input_vectors }),
+      ...(state.network_map && { network_map: state.network_map }),
+      ...(state.role_architecture && { role_architecture: state.role_architecture }),
+      ...(state.authz_candidates && { authz_candidates: state.authz_candidates }),
+      ...(state.injection_sources && { injection_sources: state.injection_sources }),
+    }),
+    getCallStatus: (): ReconCallStatus => ({
+      set_executive_summary: statusOf('set_executive_summary'),
+      set_technology_stack: statusOf('set_technology_stack'),
+      set_authentication: statusOf('set_authentication'),
+      add_endpoints: { calls: addEndpointsCalls, endpoints_seen: endpoints.length },
+      set_input_vectors: statusOf('set_input_vectors'),
+      set_network_map: statusOf('set_network_map'),
+      set_role_architecture: statusOf('set_role_architecture'),
+      set_authz_candidates: statusOf('set_authz_candidates'),
+      set_injection_sources: statusOf('set_injection_sources'),
+    }),
+  };
+}
+
+// Re-exported here so the renderer can import the shared sink type without
+// depending on pre-recon's collector by name.
+export type { SinkRef };

apps/worker/src/collectors/schema.ts

@@ -0,0 +1,29 @@
+// 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 Static, type TSchema, type TSchemaOptions, Type } from 'typebox';
+import { Value } from 'typebox/value';
+
+/**
+ * String-literal enum schema whose `Static` resolves to the exact value union.
+ *
+ * Mapping `Type.Literal` over an array loses tuple typing (`Static` widens to
+ * `never`), so enums are authored as a JSON-Schema `{ type: 'string', enum }`
+ * via `Type.Unsafe` — the same shape the previous Zod `z.enum` schemas produced,
+ * and validated at runtime by pi's TypeBox checker.
+ */
+export function stringEnum<const T extends readonly string[]>(values: T, options: TSchemaOptions = {}) {
+  return Type.Unsafe<T[number]>({ ...options, type: 'string', enum: [...values] });
+}
+
+/**
+ * Strips keys not declared on `schema` before storage, matching the previous
+ * Zod bridge's `safeParse()` behavior (Zod objects silently strip unknown
+ * keys by default; TypeBox schemas accept them unless explicitly cleaned).
+ */
+export function cleanInput<T extends TSchema>(schema: T, input: Static<T>): Static<T> {
+  return Value.Clean(schema, structuredClone(input)) as Static<T>;
+}

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

@@ -0,0 +1,472 @@
+// 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.
+
+/**
+ * Vuln Collector tools (factory parameterized by vulnerability class).
+ *
+ * Exposes 4 one-shot, TypeBox-validated tools per vuln agent (injection, xss,
+ * auth, ssrf, authz) that feed a deterministic renderer producing
+ * {class}_analysis_deliverable.md:
+ *   - set_findings_summary       — §1 executive summary + §2 dominant patterns
+ *   - set_strategic_intelligence — §3, per-class schema
+ *   - set_safe_vectors           — §4, shared schema across classes
+ *   - set_blind_spots            — §5, shared schema across classes
+ *
+ * Only set_strategic_intelligence varies by class; the collector branches on
+ * vulnClass to assemble the right schema. The other 3 tools are identical
+ * across classes.
+ *
+ * Skipped tools surface as renderer placeholders, not activity failures.
+ * getCallStatus() exposes the per-run call pattern for logging. Each schema's
+ * field-level descriptions carry the section guidance, so the agent's tool
+ * catalog surfaces it.
+ */
+
+import { defineTool, type ToolDefinition } from '@earendil-works/pi-coding-agent';
+import { type Static, type TObject, Type } from 'typebox';
+import { cleanInput } from './schema.js';
+
+// ============================================================================
+// CLASS DISCRIMINATOR
+// ============================================================================
+
+export const VULN_CLASSES = ['injection', 'xss', 'auth', 'ssrf', 'authz'] as const;
+export type VulnClass = (typeof VULN_CLASSES)[number];
+
+// ============================================================================
+// SHARED SCHEMAS — set_findings_summary, set_safe_vectors, set_blind_spots
+// ============================================================================
+
+const PatternSchema = Type.Object({
+  name: Type.String({
+    minLength: 1,
+    description:
+      'Concise pattern name, e.g. "Weak Session Management", "Reflected XSS in Search Parameter", ' +
+      '"Insufficient URL Validation".',
+  }),
+  description: Type.String({
+    minLength: 1,
+    description: 'One- to two-sentence description of the pattern observed in the codebase.',
+  }),
+  implication: Type.String({
+    minLength: 1,
+    description: 'One- to two-sentence implication for exploitation — what does this pattern enable an attacker to do.',
+  }),
+  representative_finding_ids: Type.Array(Type.String({ minLength: 1 }), {
+    minItems: 1,
+    description:
+      'IDs of findings that exhibit this pattern (e.g. ["AUTH-VULN-01", "AUTH-VULN-02"]). Must match ' +
+      'IDs the agent has assigned in the structured-output exploitation queue.',
+  }),
+});
+
+export const FindingsSummaryInputSchema = Type.Object({
+  key_outcome: Type.String({
+    minLength: 1,
+    description:
+      'One to two sentences capturing the headline result of your analysis — what was found and its ' +
+      'severity profile (e.g. "Several high-confidence SQL injection vulnerabilities were identified; ' +
+      'all findings have been passed to the exploitation phase"). Becomes Section 1 of the rendered ' +
+      'deliverable.',
+  }),
+  patterns: Type.Array(PatternSchema, {
+    description:
+      'Complete list of dominant patterns observed across findings. Pass all patterns in one call. ' +
+      'Empty array is acceptable if no recurring patterns were observed — the deliverable will render ' +
+      '"No dominant patterns identified" for Section 2 in that case.',
+  }),
+});
+
+export const SafeVectorInputSchema = Type.Object({
+  subject: Type.String({
+    minLength: 1,
+    description:
+      'The specific subject of analysis. For injection/xss runs, the input parameter name (e.g. ' +
+      '"username", "redirect_url"). For auth/ssrf runs, the component or flow name (e.g. ' +
+      '"Password Hashing", "Webhook Configuration"). For authz runs, the endpoint (e.g. ' +
+      '"POST /api/auth/logout"). The renderer maps this to the class-appropriate column header.',
+  }),
+  location: Type.String({
+    minLength: 1,
+    description:
+      'File path with line number (e.g. "controllers/authController.js:45") or endpoint URL (e.g. ' +
+      '"/profile"). For authz runs, this is the guard location specifically (e.g. ' +
+      '"middleware/auth.js:45"). The renderer maps this to the class-appropriate column header.',
+  }),
+  defense_mechanism: Type.String({
+    minLength: 1,
+    description:
+      'The robust defense observed (e.g. "Prepared Statement (Parameter Binding)", "HTML Entity ' +
+      'Encoding", "Strict URL Whitelist Validation", "bcrypt.compare for constant-time check").',
+  }),
+  render_context: Type.Optional(
+    Type.Union([Type.String(), Type.Null()], {
+      description:
+        'XSS-only: the DOM render context for the validated vector — one of HTML_BODY, HTML_ATTRIBUTE, ' +
+        'JAVASCRIPT_STRING, URL_PARAM, CSS_VALUE. Omit (or pass null) for non-XSS classes; the renderer ' +
+        'only emits this column for the XSS deliverable.',
+    }),
+  ),
+});
+
+export const SafeVectorsInputSchema = Type.Object({
+  vectors: Type.Array(SafeVectorInputSchema, {
+    description:
+      'All input vectors / components / endpoints that were analyzed and confirmed to have robust, ' +
+      'context-appropriate defenses. Empty array is acceptable but unusual — the deliverable will ' +
+      'render "No vectors confirmed secure during analysis" for Section 4 in that case. Becomes ' +
+      'Section 4 of the rendered deliverable. The renderer sorts by (subject, location) before ' +
+      'rendering, so emission order does not affect output.',
+  }),
+});
+
+export const BlindSpotItemSchema = Type.Object({
+  heading: Type.String({
+    minLength: 1,
+    description:
+      'Short heading for the blind spot (e.g. "Untraced Asynchronous Flows", ' +
+      '"Limited Visibility into Stored Procedures", "Minified JavaScript Bundle").',
+  }),
+  description: Type.String({
+    minLength: 1,
+    description:
+      'One to three sentences describing the analysis gap — what could not be traced, why, and what ' +
+      'the residual risk is.',
+  }),
+});
+
+export const BlindSpotsInputSchema = Type.Object({
+  items: Type.Array(BlindSpotItemSchema, {
+    description:
+      'Analysis constraints, untraced code paths, or other coverage gaps that should be noted. ' +
+      'Empty array is acceptable on high-coverage runs — the deliverable will render "No analysis ' +
+      'constraints or blind spots identified" for Section 5 in that case. Becomes Section 5 of the ' +
+      'rendered deliverable.',
+  }),
+});
+
+// ============================================================================
+// PER-CLASS set_strategic_intelligence SCHEMAS (flat — no nesting)
+// ============================================================================
+
+const InjectionStrategicIntelSchema = Type.Object({
+  defensive_evasion_waf: Type.String({
+    minLength: 1,
+    description:
+      'WAF behavior observed during analysis: active rules, common payloads blocked, identified ' +
+      'bypasses (e.g. "WAF blocks UNION SELECT but not time-based blind injection"). Write ' +
+      '"Not applicable — no WAF observed" if none was detected.',
+  }),
+  error_based_potential: Type.String({
+    minLength: 1,
+    description:
+      'Whether endpoints leak verbose database errors that enable error-based injection (e.g. ' +
+      '"/api/products returns verbose PostgreSQL error messages, prime target for error-based ' +
+      'exploitation"). Write "Not applicable" if no injection findings exist.',
+  }),
+  confirmed_database_technology: Type.String({
+    minLength: 1,
+    description:
+      'Database engine(s) confirmed via error syntax or function calls (e.g. "PostgreSQL, confirmed ' +
+      'via pg_sleep() and verbose error syntax"). Drives payload selection downstream. Write ' +
+      '"Not applicable" if no DB sinks in scope.',
+  }),
+});
+
+const XssStrategicIntelSchema = Type.Object({
+  csp_analysis: Type.String({
+    minLength: 1,
+    description:
+      'Content Security Policy observed and its bypassability: current policy text, critical bypasses ' +
+      "(e.g. \"script-src 'self' https://trusted-cdn.com — the trusted CDN hosts vulnerable AngularJS, " +
+      'enabling client-side template injection bypass"). Write "Not applicable — no CSP header served" ' +
+      'if none.',
+  }),
+  cookie_security: Type.String({
+    minLength: 1,
+    description:
+      'Session cookie security observations: HttpOnly, Secure, SameSite flags, and storage mechanism ' +
+      '(e.g. "Primary session cookie `sessionid` is missing HttpOnly; tokens are also stored in ' +
+      'localStorage, both accessible to JavaScript"). Drives exfiltration strategy.',
+  }),
+});
+
+const AuthStrategicIntelSchema = Type.Object({
+  authentication_method: Type.String({
+    minLength: 1,
+    description:
+      'How users authenticate: JWT, session cookie, OAuth, SAML, etc. Include any algorithm or library ' +
+      'details (e.g. "JWT (RS256) with hardcoded private key in lib/insecurity.ts:23").',
+  }),
+  session_token_details: Type.String({
+    minLength: 1,
+    description:
+      'Where tokens live and how they are protected: cookie name, storage mechanism (cookie vs ' +
+      'localStorage), cookie flags, expiration (e.g. "JWT stored in localStorage under key `token`; ' +
+      'cookie copy lacks HttpOnly/Secure/SameSite; 6-hour TTL with no revocation").',
+  }),
+  password_policy: Type.String({
+    minLength: 1,
+    description:
+      'Observed server-side password policy and storage: complexity rules, hashing algorithm, salt, ' +
+      '(e.g. "MD5 without salt via crypto.createHash; no server-side complexity policy; client-side ' +
+      '5-char minimum trivially bypassed").',
+  }),
+});
+
+const SsrfStrategicIntelSchema = Type.Object({
+  http_client_library: Type.String({
+    minLength: 1,
+    description:
+      'HTTP client library/libraries used for outbound requests (e.g. "axios 1.6", "node-fetch", ' +
+      '"requests", "HttpClient (Spring)"). Include version where it informs known bypass techniques.',
+  }),
+  request_architecture: Type.String({
+    minLength: 1,
+    description:
+      'How outbound requests are constructed and routed: proxy/middleware patterns, internal routing ' +
+      'rules (e.g. "Webhook URLs are POSTed directly without an outbound proxy; redirects are ' +
+      'followed by default with no maxRedirects limit").',
+  }),
+  internal_services: Type.String({
+    minLength: 1,
+    description:
+      'Internal endpoints, services, or cloud-metadata addresses discovered during analysis that an ' +
+      'SSRF could reach (e.g. "169.254.169.254 (AWS IMDS), internal admin API at admin.internal:8443, ' +
+      'PostgreSQL on localhost:5432").',
+  }),
+});
+
+const AuthzStrategicIntelSchema = Type.Object({
+  session_management_architecture: Type.String({
+    minLength: 1,
+    description:
+      'Session and authentication architecture relevant to authorization decisions: where user identity ' +
+      'comes from, whether the user ID is trusted by downstream guards (e.g. "JWT tokens in cookies; ' +
+      'user ID extracted from `req.user.id` and used directly in DB queries without ownership ' +
+      're-validation").',
+  }),
+  role_permission_model: Type.String({
+    minLength: 1,
+    description:
+      'Roles, capabilities, and where they live: identified roles, their privilege levels, and where ' +
+      'role/permission data is stored (e.g. "Three roles: user, moderator, admin. Role embedded in ' +
+      'JWT and database; checks inconsistent — many admin routes only check `req.user` presence").',
+  }),
+  resource_access_patterns: Type.String({
+    minLength: 1,
+    description:
+      'How resource IDs flow through the system and ownership patterns: e.g. "Most endpoints use path ' +
+      'parameters for resource IDs (/api/users/{id}); IDs are passed to DB queries without ownership ' +
+      'validation". Critical for IDOR exploitation.',
+  }),
+  workflow_implementation: Type.String({
+    minLength: 1,
+    description:
+      'Multi-step processes and state transitions: how workflow stages are tracked, whether prior-state ' +
+      'checks are enforced (e.g. "Multi-step processes use status fields in database; status ' +
+      'transitions do not verify prior state completion"). Drives context-based authz exploitation.',
+  }),
+});
+
+export const STRATEGIC_INTEL_SCHEMAS: Record<VulnClass, TObject> = {
+  injection: InjectionStrategicIntelSchema,
+  xss: XssStrategicIntelSchema,
+  auth: AuthStrategicIntelSchema,
+  ssrf: SsrfStrategicIntelSchema,
+  authz: AuthzStrategicIntelSchema,
+};
+
+// ============================================================================
+// EXPORTED TYPES
+// ============================================================================
+
+export type Pattern = Static<typeof PatternSchema>;
+export type FindingsSummaryInput = Static<typeof FindingsSummaryInputSchema>;
+export type SafeVectorInput = Static<typeof SafeVectorInputSchema>;
+export type SafeVectorsInput = Static<typeof SafeVectorsInputSchema>;
+export type BlindSpotItem = Static<typeof BlindSpotItemSchema>;
+export type BlindSpotsInput = Static<typeof BlindSpotsInputSchema>;
+
+export type InjectionStrategicIntel = Static<typeof InjectionStrategicIntelSchema>;
+export type XssStrategicIntel = Static<typeof XssStrategicIntelSchema>;
+export type AuthStrategicIntel = Static<typeof AuthStrategicIntelSchema>;
+export type SsrfStrategicIntel = Static<typeof SsrfStrategicIntelSchema>;
+export type AuthzStrategicIntel = Static<typeof AuthzStrategicIntelSchema>;
+
+// Discriminated by the agent class context — the renderer reads only the
+// sub-fields that apply to the active class.
+export type StrategicIntelligenceInput =
+  | InjectionStrategicIntel
+  | XssStrategicIntel
+  | AuthStrategicIntel
+  | SsrfStrategicIntel
+  | AuthzStrategicIntel;
+
+export interface VulnCollectorData {
+  readonly findings_summary?: FindingsSummaryInput;
+  readonly strategic_intelligence?: StrategicIntelligenceInput;
+  readonly safe_vectors?: SafeVectorsInput;
+  readonly blind_spots?: BlindSpotsInput;
+}
+
+export const VULN_TOOLS = [
+  'set_findings_summary',
+  'set_strategic_intelligence',
+  'set_safe_vectors',
+  'set_blind_spots',
+] as const;
+
+export type VulnToolName = (typeof VULN_TOOLS)[number];
+
+export type VulnToolStatus = 'called' | 'skipped';
+
+export type VulnCallStatus = Readonly<Record<VulnToolName, VulnToolStatus>>;
+
+// ============================================================================
+// 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
+// ============================================================================
+
+interface VulnState {
+  findings_summary?: FindingsSummaryInput;
+  strategic_intelligence?: StrategicIntelligenceInput;
+  safe_vectors?: SafeVectorsInput;
+  blind_spots?: BlindSpotsInput;
+}
+
+export interface VulnCollector {
+  tools: ToolDefinition[];
+  getAll(): VulnCollectorData;
+  getCallStatus(): VulnCallStatus;
+}
+
+export function createVulnCollector(vulnClass: VulnClass): VulnCollector {
+  const state: VulnState = {};
+
+  function alreadyCalled(toolName: VulnToolName) {
+    return errorResult(
+      `${toolName} has already been called. Each tool may only be called once per run.`,
+      'DuplicateError',
+      false,
+    );
+  }
+
+  const setFindingsSummary = defineTool({
+    name: 'set_findings_summary',
+    label: 'Set Findings Summary',
+    description:
+      'Record the executive summary headline and the dominant vulnerability patterns observed across ' +
+      'your findings. Call exactly once before terminating. Becomes Section 1 (key outcome) and ' +
+      'Section 2 (patterns) of the rendered deliverable — this is the load-bearing emission for the ' +
+      'narrative .md and is required. Duplicate calls return "already called" and are no-ops. Empty ' +
+      'patterns array is acceptable (renders as "No dominant patterns identified") but key_outcome ' +
+      'is always required.',
+    parameters: FindingsSummaryInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.findings_summary) return alreadyCalled('set_findings_summary');
+      state.findings_summary = cleanInput(FindingsSummaryInputSchema, input);
+      return successResult({ set: 'set_findings_summary' });
+    },
+  });
+
+  const intelSchema = STRATEGIC_INTEL_SCHEMAS[vulnClass];
+  const setStrategicIntelligence = defineTool({
+    name: 'set_strategic_intelligence',
+    label: 'Set Strategic Intelligence',
+    description:
+      `Record the environmental and defensive intelligence relevant to exploiting the ${vulnClass} ` +
+      'findings. Call exactly once before terminating. Becomes Section 3 of the rendered deliverable ' +
+      `and is the section the downstream exploit-${vulnClass} agent reads for strategic context. ` +
+      'Required. Duplicate calls return "already called" and are no-ops. Write "Not applicable" as ' +
+      'the field value when a sub-field does not apply to this run (rather than omitting).',
+    parameters: intelSchema,
+    async execute(_toolCallId, input) {
+      if (state.strategic_intelligence) return alreadyCalled('set_strategic_intelligence');
+      state.strategic_intelligence = cleanInput(intelSchema, input) as unknown as StrategicIntelligenceInput;
+      return successResult({ set: 'set_strategic_intelligence' });
+    },
+  });
+
+  const setSafeVectors = defineTool({
+    name: 'set_safe_vectors',
+    label: 'Set Safe Vectors',
+    description:
+      'Record the input vectors, components, or endpoints that were analyzed and confirmed to have ' +
+      'robust, context-appropriate defenses. Call exactly once before terminating. Becomes Section 4 ' +
+      'of the rendered deliverable. Recommended (empty array is acceptable on runs where no vectors ' +
+      'were validated as safe, but explicit emission is preferred). The renderer sorts by ' +
+      '(subject, location) before rendering, so emission order does not affect output. Duplicate ' +
+      'calls return "already called" and are no-ops.',
+    parameters: SafeVectorsInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.safe_vectors) return alreadyCalled('set_safe_vectors');
+      state.safe_vectors = cleanInput(SafeVectorsInputSchema, input);
+      return successResult({ set: 'set_safe_vectors', count: input.vectors.length });
+    },
+  });
+
+  const setBlindSpots = defineTool({
+    name: 'set_blind_spots',
+    label: 'Set Blind Spots',
+    description:
+      'Record analysis constraints, untraced code paths, or other coverage gaps. Call exactly once ' +
+      'before terminating. Becomes Section 5 of the rendered deliverable. Recommended (empty array ' +
+      'is acceptable on high-coverage runs, but explicit emission is preferred — readers expect ' +
+      'either documented gaps or an explicit "no gaps" signal). Duplicate calls return "already ' +
+      'called" and are no-ops.',
+    parameters: BlindSpotsInputSchema,
+    async execute(_toolCallId, input) {
+      if (state.blind_spots) return alreadyCalled('set_blind_spots');
+      state.blind_spots = cleanInput(BlindSpotsInputSchema, input);
+      return successResult({ set: 'set_blind_spots', count: input.items.length });
+    },
+  });
+
+  function statusOf<K extends VulnToolName>(key: K): VulnToolStatus {
+    const flagMap: Record<VulnToolName, unknown> = {
+      set_findings_summary: state.findings_summary,
+      set_strategic_intelligence: state.strategic_intelligence,
+      set_safe_vectors: state.safe_vectors,
+      set_blind_spots: state.blind_spots,
+    };
+    return flagMap[key] ? 'called' : 'skipped';
+  }
+
+  return {
+    tools: [setFindingsSummary, setStrategicIntelligence, setSafeVectors, setBlindSpots],
+    getAll: (): VulnCollectorData => ({
+      ...(state.findings_summary && { findings_summary: state.findings_summary }),
+      ...(state.strategic_intelligence && { strategic_intelligence: state.strategic_intelligence }),
+      ...(state.safe_vectors && { safe_vectors: state.safe_vectors }),
+      ...(state.blind_spots && { blind_spots: state.blind_spots }),
+    }),
+    getCallStatus: (): VulnCallStatus => ({
+      set_findings_summary: statusOf('set_findings_summary'),
+      set_strategic_intelligence: statusOf('set_strategic_intelligence'),
+      set_safe_vectors: statusOf('set_safe_vectors'),
+      set_blind_spots: statusOf('set_blind_spots'),
+    }),
+  };
+}

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/mcp-server/pre-recon-collector.ts

@@ -1,620 +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.
-
-/**
- * Pre-Recon Collector MCP Server
- *
- * Exposes seven Zod-validated MCP tools, one per section of the
- * pre_recon_deliverable.md report. Every tool is one-shot (write-once;
- * duplicate calls return DuplicateError). A skipped tool renders a placeholder
- * rather than failing the activity. After the agent finishes, the host calls
- * getAll() to harvest the typed payload bag, getCallStatus() to log the
- * per-run call pattern, and runs the deterministic renderer to produce the
- * deliverable Markdown.
- *
- * Each Zod schema's field-level descriptions carry the section guidance, so
- * the SDK injects it into the agent's tool catalog.
- */
-
-import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-
-// ============================================================================
-// SHARED SCHEMA
-// ============================================================================
-
-export const SinkRefSchema = z.object({
-  location: z
-    .string()
-    .min(1)
-    .describe(
-      'File path with line number (e.g., "templates/render.js:34") or richer prose ' +
-        '(e.g., "innerHTML at templates/render.js:34", "lines 45-67"). Must contain enough ' +
-        'detail for a downstream agent to find the exact location.',
-    ),
-  sink_function: z
-    .string()
-    .min(1)
-    .describe('The sink function or property name (e.g., "innerHTML", "axios.get", "eval", "document.write").'),
-  notes: z
-    .string()
-    .nullable()
-    .optional()
-    .describe(
-      'Optional context — render-context detail, attribute name, scope hints, or anything ' +
-        'a downstream agent needs to act on this sink. Omit when the location and sink_function ' +
-        'are sufficient on their own.',
-    ),
-});
-
-export type SinkRef = z.infer<typeof SinkRefSchema>;
-
-// ============================================================================
-// PER-TOOL INPUT SCHEMAS
-// ============================================================================
-
-export const ExecutiveSummaryInputSchema = z.object({
-  text: z
-    .string()
-    .min(1)
-    .describe(
-      "Provide a 2-3 paragraph overview of the application's security posture, highlighting " +
-        'the most critical attack surfaces and architectural security decisions. Becomes ' +
-        'Section 1 of the rendered deliverable.',
-    ),
-});
-
-const ArchitectureSchema = z.object({
-  framework_and_language: z
-    .string()
-    .min(1)
-    .describe('Framework and language details with their security implications.'),
-  architectural_pattern: z
-    .string()
-    .min(1)
-    .describe('Architectural pattern (monolith, microservices, hybrid) with trust boundary analysis.'),
-  critical_security_components: z
-    .string()
-    .min(1)
-    .describe('Critical security components with focus on auth, authz, and data protection.'),
-});
-
-const DataSecuritySchema = z.object({
-  database_security: z
-    .string()
-    .min(1)
-    .describe('Analyze encryption, access controls, and query safety in database interactions.'),
-  data_flow_security: z
-    .string()
-    .min(1)
-    .describe('Identify sensitive data paths and the protection mechanisms applied along them.'),
-  multi_tenant_isolation: z
-    .string()
-    .min(1)
-    .describe(
-      'Assess tenant separation effectiveness. If the application is single-tenant, state that ' +
-        'explicitly rather than leaving the field thin.',
-    ),
-});
-
-const AttackSurfaceSchema = z.object({
-  external_entry_points: z
-    .string()
-    .min(1)
-    .describe('Detailed analysis of each public interface that is network-accessible.'),
-  internal_service_communication: z
-    .string()
-    .min(1)
-    .describe(
-      'Trust relationships and security assumptions between network-reachable services. ' +
-        'If the application is a single service with no internal RPC fabric, state that.',
-    ),
-  input_validation_patterns: z
-    .string()
-    .min(1)
-    .describe('How user input is handled and validated in network-accessible endpoints.'),
-  background_processing: z
-    .string()
-    .min(1)
-    .describe(
-      'Async job security and privilege models for jobs triggered by network requests. ' +
-        'If no async/background processing exists, state that.',
-    ),
-});
-
-const InfrastructureSchema = z.object({
-  secrets_management: z.string().min(1).describe('How secrets are stored, rotated, and accessed.'),
-  configuration_security: z
-    .string()
-    .min(1)
-    .describe(
-      'Environment separation and secret handling. Specifically search for infrastructure ' +
-        'configuration (e.g., Nginx, Kubernetes Ingress, CDN settings) that defines security ' +
-        'headers like Strict-Transport-Security (HSTS) and Cache-Control, and report what was found.',
-    ),
-  external_dependencies: z.string().min(1).describe('Third-party services and their security implications.'),
-  monitoring_and_logging: z
-    .string()
-    .min(1)
-    .describe('Security event visibility — what is logged, where it goes, and who can see it.'),
-});
-
-export const ApplicationIntelligenceInputSchema = z.object({
-  architecture: ArchitectureSchema.describe(
-    'Architecture & Technology Stack — driven by the Architecture Scanner sub-agent. ' +
-      'Becomes Section 2 of the rendered deliverable.',
-  ),
-  data_security: DataSecuritySchema.describe(
-    'Data Security & Storage — driven by the Data Security Auditor sub-agent. ' +
-      'Becomes Section 4 of the rendered deliverable.',
-  ),
-  attack_surface: AttackSurfaceSchema.describe(
-    'Attack Surface Analysis — driven by Entry Point Mapper + Architecture Scanner sub-agents. ' +
-      'Only include entry points confirmed to be in-scope (network-reachable). ' +
-      'Becomes Section 5 of the rendered deliverable.',
-  ),
-  infrastructure: InfrastructureSchema.describe(
-    'Infrastructure & Operational Security. Becomes Section 6 of the rendered deliverable.',
-  ),
-});
-
-export const AuthDeepDiveInputSchema = z.object({
-  authentication_mechanisms: z
-    .string()
-    .min(1)
-    .describe(
-      'Authentication mechanisms and their security properties. MUST include an exhaustive list of ' +
-        'all API endpoints used for authentication (e.g., login, logout, token refresh, password reset).',
-    ),
-  session_management: z
-    .string()
-    .min(1)
-    .describe(
-      'Session management and token security. Pinpoint the exact file and line(s) of code where ' +
-        'session cookie flags (HttpOnly, Secure, SameSite) are configured.',
-    ),
-  authz_model: z.string().min(1).describe('Authorization model and potential bypass scenarios.'),
-  multi_tenancy: z
-    .string()
-    .min(1)
-    .describe('Multi-tenancy security implementation. If the application is single-tenant, state that explicitly.'),
-  sso_oauth_oidc: z
-    .string()
-    .nullable()
-    .describe(
-      'SSO/OAuth/OIDC flows: identify the callback endpoints and locate the specific code that ' +
-        'validates the state and nonce parameters. Set null only if the application has no SSO/OAuth/OIDC ' +
-        'integration at all.',
-    ),
-});
-
-export const CodebaseIndexingInputSchema = z.object({
-  text: z
-    .string()
-    .min(1)
-    .describe(
-      "A detailed, multi-sentence paragraph describing the codebase's directory structure, " +
-        'organization, and significant tools or conventions used (e.g., build orchestration, code ' +
-        'generation, testing frameworks). Focus on how this structure impacts discoverability of ' +
-        'security-relevant components.',
-    ),
-});
-
-export const CriticalFilePathsInputSchema = z.object({
-  configuration: z
-    .array(z.string().min(1))
-    .describe('Configuration files (e.g., config/server.yaml, Dockerfile, docker-compose.yml).'),
-  authentication_and_authorization: z
-    .array(z.string().min(1))
-    .describe(
-      'Auth/authz files (e.g., auth/jwt_middleware.go, internal/user/permissions.go, ' +
-        'config/initializers/session_store.rb, src/services/oauth_callback.js).',
-    ),
-  api_and_routing: z
-    .array(z.string().min(1))
-    .describe(
-      'API and routing files (e.g., cmd/api/main.go, internal/handlers/user_routes.go, ' +
-        'ts/graphql/schema.graphql).',
-    ),
-  data_models_and_db: z
-    .array(z.string().min(1))
-    .describe(
-      'Data model and DB interaction files (e.g., db/migrations/001_initial.sql, ' +
-        'internal/models/user.go, internal/repository/sql_queries.go).',
-    ),
-  dependency_manifests: z
-    .array(z.string().min(1))
-    .describe('Dependency manifests (e.g., go.mod, package.json, requirements.txt).'),
-  sensitive_data_and_secrets: z
-    .array(z.string().min(1))
-    .describe(
-      'Sensitive data and secrets handling (e.g., internal/utils/encryption.go, ' + 'internal/secrets/manager.go).',
-    ),
-  middleware_and_input_validation: z
-    .array(z.string().min(1))
-    .describe(
-      'Middleware and input validation (e.g., internal/middleware/validator.go, ' +
-        'internal/handlers/input_parsers.go).',
-    ),
-  logging_and_monitoring: z
-    .array(z.string().min(1))
-    .describe('Logging and monitoring (e.g., internal/logging/logger.go, config/monitoring.yaml).'),
-  infrastructure_and_deployment: z
-    .array(z.string().min(1))
-    .describe(
-      'Infrastructure and deployment (e.g., infra/pulumi/main.go, kubernetes/deploy.yaml, ' +
-        'nginx.conf, gateway-ingress.yaml).',
-    ),
-});
-
-export const XssSinksInputSchema = z.object({
-  applicable: z
-    .boolean()
-    .describe(
-      'False only if the application has no web frontend at all. Otherwise true, even if no ' +
-        'sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
-    ),
-  html_body: z
-    .array(SinkRefSchema)
-    .describe(
-      'HTML Body Context sinks: element.innerHTML, element.outerHTML, document.write(), ' +
-        'document.writeln(), element.insertAdjacentHTML(), Range.createContextualFragment(), ' +
-        'and jQuery sinks like add(), after(), append(), before(), html(), prepend(), replaceWith(), wrap().',
-    ),
-  html_attribute: z
-    .array(SinkRefSchema)
-    .describe(
-      'HTML Attribute Context sinks: event handlers (onclick, onerror, onmouseover, onload, onfocus), ' +
-        'URL-based attributes (href, src, formaction, action, background, data), the style attribute, ' +
-        'iframe srcdoc, and general attributes (value, id, class, name, alt) when quotes are escaped.',
-    ),
-  javascript: z
-    .array(SinkRefSchema)
-    .describe(
-      'JavaScript Context sinks: eval(), Function() constructor, setTimeout() / setInterval() ' +
-        'with string arguments, and direct writes of user data into a <script> tag.',
-    ),
-  css: z
-    .array(SinkRefSchema)
-    .describe(
-      'CSS Context sinks: element.style properties (e.g., element.style.backgroundImage) and ' +
-        'direct writes of user data into a <style> tag.',
-    ),
-  url: z
-    .array(SinkRefSchema)
-    .describe(
-      'URL Context sinks: location / window.location, location.href, location.replace(), ' +
-        'location.assign(), window.open(), history.pushState(), history.replaceState(), ' +
-        'URL.createObjectURL(), and jQuery selector $(userInput) in older versions.',
-    ),
-});
-
-export const SsrfSinksInputSchema = z.object({
-  applicable: z
-    .boolean()
-    .describe(
-      'False only if the application makes no outbound requests at all. Otherwise true, even if ' +
-        'no sinks were found in a given category — empty arrays mean "scanned this category, no sinks found".',
-    ),
-  http_clients: z
-    .array(SinkRefSchema)
-    .describe(
-      'HTTP(S) clients: curl, requests (Python), axios (Node.js), fetch (JavaScript/Node.js), ' +
-        'net/http (Go), HttpClient (Java/.NET), urllib (Python), RestTemplate, WebClient, OkHttp, Apache HttpClient.',
-    ),
-  raw_sockets: z
-    .array(SinkRefSchema)
-    .describe(
-      'Raw sockets and connect APIs: Socket.connect, net.Dial (Go), socket.connect (Python), ' +
-        'TcpClient, UdpClient, NetworkStream, java.net.Socket, java.net.URL.openConnection().',
-    ),
-  url_openers: z
-    .array(SinkRefSchema)
-    .describe(
-      'URL openers and file includes: file_get_contents (PHP), fopen, include_once, require_once, ' +
-        'new URL().openStream() (Java), urllib.urlopen (Python), fs.readFile with URLs, ' +
-        'import() with dynamic URLs, loadHTML / loadXML with external sources.',
-    ),
-  redirect_handlers: z
-    .array(SinkRefSchema)
-    .describe(
-      'Redirect and "next URL" handlers: auto-follow redirects in HTTP clients, framework Location ' +
-        'handlers (response.redirect), URL validation in redirect chains, "Continue to" / "Return URL" parameters.',
-    ),
-  headless_browsers: z
-    .array(SinkRefSchema)
-    .describe(
-      'Headless browsers and render engines: Puppeteer (page.goto, page.setContent), ' +
-        'Playwright (page.navigate, page.route), Selenium WebDriver navigation, html-to-pdf converters ' +
-        '(wkhtmltopdf, Puppeteer PDF), and SSR with external content.',
-    ),
-  media_processors: z
-    .array(SinkRefSchema)
-    .describe(
-      'Media processors: ImageMagick (convert, identify with URLs), GraphicsMagick, FFmpeg with ' +
-        'network sources, wkhtmltopdf, Ghostscript with URL inputs, image optimization services with URL parameters.',
-    ),
-  link_preview: z
-    .array(SinkRefSchema)
-    .describe(
-      'Link preview and unfurlers: chat application link expanders, CMS link preview generators, ' +
-        'oEmbed endpoint fetchers, social media card generators, URL metadata extractors.',
-    ),
-  webhook_testers: z
-    .array(SinkRefSchema)
-    .describe(
-      'Webhook testers and callback verifiers: "ping my webhook" functionality, outbound callback ' +
-        'verification, health check notifications, event delivery confirmations, API endpoint validation tools.',
-    ),
-  sso_oidc_discovery: z
-    .array(SinkRefSchema)
-    .describe(
-      'SSO/OIDC discovery and JWKS fetchers: OpenID Connect discovery endpoints, JWKS fetchers, ' +
-        'OAuth authorization server metadata, SAML metadata fetchers, federation metadata retrievers.',
-    ),
-  importers: z
-    .array(SinkRefSchema)
-    .describe(
-      'Importers and data loaders: "import from URL" functionality, CSV/JSON/XML remote loaders, ' +
-        'RSS/Atom feed readers, API data synchronization, configuration file fetchers.',
-    ),
-  package_installers: z
-    .array(SinkRefSchema)
-    .describe(
-      'Package/plugin/theme installers: "install from URL" features, package managers with remote ' +
-        'sources, plugin/theme downloaders, update mechanisms with remote checks, dependency resolution ' +
-        'with external repos.',
-    ),
-  monitoring_and_health: z
-    .array(SinkRefSchema)
-    .describe(
-      'Monitoring and health check frameworks: URL pingers and uptime checkers, health check ' +
-        'endpoints, monitoring probe systems, alerting webhook senders, performance testing tools.',
-    ),
-  cloud_metadata: z
-    .array(SinkRefSchema)
-    .describe(
-      'Cloud metadata helpers: AWS/GCP/Azure instance metadata callers, cloud service discovery ' +
-        'mechanisms, container orchestration API clients, infrastructure metadata fetchers, service mesh ' +
-        'configuration retrievers.',
-    ),
-});
-
-// ============================================================================
-// EXPORTED TYPES
-// ============================================================================
-
-export type ExecutiveSummaryInput = z.infer<typeof ExecutiveSummaryInputSchema>;
-export type ApplicationIntelligenceInput = z.infer<typeof ApplicationIntelligenceInputSchema>;
-export type AuthDeepDiveInput = z.infer<typeof AuthDeepDiveInputSchema>;
-export type CodebaseIndexingInput = z.infer<typeof CodebaseIndexingInputSchema>;
-export type CriticalFilePathsInput = z.infer<typeof CriticalFilePathsInputSchema>;
-export type XssSinksInput = z.infer<typeof XssSinksInputSchema>;
-export type SsrfSinksInput = z.infer<typeof SsrfSinksInputSchema>;
-
-export interface PreReconData {
-  readonly executive_summary?: ExecutiveSummaryInput;
-  readonly application_intelligence?: ApplicationIntelligenceInput;
-  readonly auth_deep_dive?: AuthDeepDiveInput;
-  readonly codebase_indexing?: CodebaseIndexingInput;
-  readonly critical_file_paths?: CriticalFilePathsInput;
-  readonly xss_sinks?: XssSinksInput;
-  readonly ssrf_sinks?: SsrfSinksInput;
-}
-
-export const PRE_RECON_ONE_SHOT_TOOLS = [
-  'set_executive_summary',
-  'set_application_intelligence',
-  'set_auth_deep_dive',
-  'set_codebase_indexing',
-  'set_critical_file_paths',
-  'set_xss_sinks',
-  'set_ssrf_sinks',
-] as const;
-
-export type PreReconToolName = (typeof PRE_RECON_ONE_SHOT_TOOLS)[number];
-
-export type PreReconToolStatus = 'called' | 'skipped';
-
-export type PreReconCallStatus = Readonly<Record<PreReconToolName, PreReconToolStatus>>;
-
-// ============================================================================
-// RESPONSE HELPERS
-// ============================================================================
-
-interface ToolResult {
-  [x: string]: unknown;
-  content: Array<{ type: 'text'; text: string }>;
-  isError: boolean;
-}
-
-function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
-  return {
-    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
-    isError: response.status === 'error',
-  };
-}
-
-function successResult(data: Record<string, unknown>): ToolResult {
-  return createToolResult({ status: 'success', ...data });
-}
-
-function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
-  return createToolResult({ status: 'error', message, errorType, retryable });
-}
-
-// ============================================================================
-// SERVER FACTORY
-// ============================================================================
-
-export interface PreReconCollectorServer {
-  server: McpSdkServerConfigWithInstance;
-  getAll(): PreReconData;
-  getCallStatus(): PreReconCallStatus;
-}
-
-export function createPreReconCollectorServer(): PreReconCollectorServer {
-  const state: {
-    executive_summary?: ExecutiveSummaryInput;
-    application_intelligence?: ApplicationIntelligenceInput;
-    auth_deep_dive?: AuthDeepDiveInput;
-    codebase_indexing?: CodebaseIndexingInput;
-    critical_file_paths?: CriticalFilePathsInput;
-    xss_sinks?: XssSinksInput;
-    ssrf_sinks?: SsrfSinksInput;
-  } = {};
-
-  function alreadyCalled(toolName: PreReconToolName): ToolResult {
-    return errorResult(
-      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
-      'DuplicateError',
-      false,
-    );
-  }
-
-  const setExecutiveSummary = tool(
-    'set_executive_summary',
-    "Record the application's overall security posture as a short executive summary. " +
-      'Call exactly once before terminating. Becomes Section 1 of the rendered deliverable. ' +
-      'Duplicate calls are rejected.',
-    ExecutiveSummaryInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.executive_summary) return alreadyCalled('set_executive_summary');
-      state.executive_summary = input;
-      return successResult({ set: 'set_executive_summary' });
-    },
-  );
-
-  const setApplicationIntelligence = tool(
-    'set_application_intelligence',
-    'Record the composite application intelligence — architecture, data security, attack surface, ' +
-      'and infrastructure — in a single call. Call exactly once before terminating. ' +
-      'Becomes Sections 2, 4, 5, and 6 of the rendered deliverable. Duplicate calls are rejected.',
-    ApplicationIntelligenceInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.application_intelligence) return alreadyCalled('set_application_intelligence');
-      state.application_intelligence = input;
-      return successResult({ set: 'set_application_intelligence' });
-    },
-  );
-
-  const setAuthDeepDive = tool(
-    'set_auth_deep_dive',
-    'Record the authentication & authorization deep dive. Call exactly once before terminating. ' +
-      'Becomes Section 3 of the rendered deliverable. Duplicate calls are rejected.',
-    AuthDeepDiveInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.auth_deep_dive) return alreadyCalled('set_auth_deep_dive');
-      state.auth_deep_dive = input;
-      return successResult({ set: 'set_auth_deep_dive' });
-    },
-  );
-
-  const setCodebaseIndexing = tool(
-    'set_codebase_indexing',
-    'Record the overall codebase indexing narrative. Call exactly once before terminating. ' +
-      'Becomes Section 7 of the rendered deliverable. Duplicate calls are rejected.',
-    CodebaseIndexingInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.codebase_indexing) return alreadyCalled('set_codebase_indexing');
-      state.codebase_indexing = input;
-      return successResult({ set: 'set_codebase_indexing' });
-    },
-  );
-
-  const setCriticalFilePaths = tool(
-    'set_critical_file_paths',
-    'Record the catalog of critical file paths grouped by security relevance. Call exactly once ' +
-      'before terminating. Becomes Section 8 of the rendered deliverable. The next agent uses this ' +
-      'as a starting point for manual review. Duplicate calls are rejected.',
-    CriticalFilePathsInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.critical_file_paths) return alreadyCalled('set_critical_file_paths');
-      state.critical_file_paths = input;
-      return successResult({ set: 'set_critical_file_paths' });
-    },
-  );
-
-  const setXssSinks = tool(
-    'set_xss_sinks',
-    'Record discovered XSS sinks grouped by render context. Call exactly once before terminating. ' +
-      'If the application has no web frontend at all, set applicable=false; otherwise populate each ' +
-      'render-context array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
-      "the vuln-xss agent's testing todos downstream. Becomes Section 9 of the rendered deliverable. " +
-      'Duplicate calls are rejected.',
-    XssSinksInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.xss_sinks) return alreadyCalled('set_xss_sinks');
-      state.xss_sinks = input;
-      return successResult({ set: 'set_xss_sinks' });
-    },
-  );
-
-  const setSsrfSinks = tool(
-    'set_ssrf_sinks',
-    'Record discovered SSRF sinks grouped by sink category. Call exactly once before terminating. ' +
-      'If the application makes no outbound requests at all, set applicable=false; otherwise populate ' +
-      'each category array (empty arrays mean "scanned, no sinks of this kind"). This list drives ' +
-      "the vuln-ssrf agent's testing todos downstream. Becomes Section 10 of the rendered deliverable. " +
-      'Duplicate calls are rejected.',
-    SsrfSinksInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.ssrf_sinks) return alreadyCalled('set_ssrf_sinks');
-      state.ssrf_sinks = input;
-      return successResult({ set: 'set_ssrf_sinks' });
-    },
-  );
-
-  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
-    name: 'pre-recon-collector',
-    version: '1.0.0',
-    tools: [
-      setExecutiveSummary,
-      setApplicationIntelligence,
-      setAuthDeepDive,
-      setCodebaseIndexing,
-      setCriticalFilePaths,
-      setXssSinks,
-      setSsrfSinks,
-    ],
-  });
-
-  function statusOf<K extends PreReconToolName>(key: K): PreReconToolStatus {
-    const flagMap: Record<PreReconToolName, unknown> = {
-      set_executive_summary: state.executive_summary,
-      set_application_intelligence: state.application_intelligence,
-      set_auth_deep_dive: state.auth_deep_dive,
-      set_codebase_indexing: state.codebase_indexing,
-      set_critical_file_paths: state.critical_file_paths,
-      set_xss_sinks: state.xss_sinks,
-      set_ssrf_sinks: state.ssrf_sinks,
-    };
-    return flagMap[key] ? 'called' : 'skipped';
-  }
-
-  return {
-    server,
-    getAll: (): PreReconData => ({
-      ...(state.executive_summary && { executive_summary: state.executive_summary }),
-      ...(state.application_intelligence && { application_intelligence: state.application_intelligence }),
-      ...(state.auth_deep_dive && { auth_deep_dive: state.auth_deep_dive }),
-      ...(state.codebase_indexing && { codebase_indexing: state.codebase_indexing }),
-      ...(state.critical_file_paths && { critical_file_paths: state.critical_file_paths }),
-      ...(state.xss_sinks && { xss_sinks: state.xss_sinks }),
-      ...(state.ssrf_sinks && { ssrf_sinks: state.ssrf_sinks }),
-    }),
-    getCallStatus: (): PreReconCallStatus => ({
-      set_executive_summary: statusOf('set_executive_summary'),
-      set_application_intelligence: statusOf('set_application_intelligence'),
-      set_auth_deep_dive: statusOf('set_auth_deep_dive'),
-      set_codebase_indexing: statusOf('set_codebase_indexing'),
-      set_critical_file_paths: statusOf('set_critical_file_paths'),
-      set_xss_sinks: statusOf('set_xss_sinks'),
-      set_ssrf_sinks: statusOf('set_ssrf_sinks'),
-    }),
-  };
-}

apps/worker/src/mcp-server/recon-collector.ts

@@ -1,818 +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.
-
-/**
- * Recon Collector MCP Server
- *
- * Exposes nine Zod-validated MCP tools that feed the recon_deliverable.md
- * renderer — eight one-shot `set_*` tools, one per deliverable section, plus a
- * multi-call `add_endpoints` tool that lets the agent split a large API
- * inventory across calls (the only catalog whose realistic payload threatens
- * the per-turn output cap).
- *
- * A skipped tool renders a "not provided" placeholder in that section rather
- * than failing the activity. getCallStatus() exposes the per-run call pattern
- * for logging. Each Zod schema's field-level descriptions carry the section
- * guidance, so the SDK injects it into the agent's tool catalog.
- */
-
-import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { z } from 'zod';
-import { type SinkRef, SinkRefSchema } from './pre-recon-collector.js';
-
-// ============================================================================
-// PER-TOOL INPUT SCHEMAS
-// ============================================================================
-
-export const ExecutiveSummaryInputSchema = z.object({
-  text: z
-    .string()
-    .min(1)
-    .describe(
-      "A brief overview of the application's purpose, core technology stack " +
-        '(e.g., Next.js, Cloudflare), and the primary user-facing components that ' +
-        'constitute the attack surface. Becomes Section 1 of the rendered deliverable.',
-    ),
-});
-
-export const TechnologyStackInputSchema = z.object({
-  frontend: z.string().min(1).describe('Framework, key libraries, and authentication libraries used on the frontend.'),
-  backend: z.string().min(1).describe('Language, framework, and key dependencies used on the backend.'),
-  infrastructure: z
-    .string()
-    .min(1)
-    .describe('Hosting provider, CDN, database type, and other infrastructure components.'),
-});
-
-const SessionFlowSchema = z.object({
-  entry_points: z.string().min(1).describe('Authentication entry points (e.g., /login, /register, /auth/sso).'),
-  mechanism: z
-    .string()
-    .min(1)
-    .describe(
-      'Describe the step-by-step authentication process: credential submission, token generation, ' +
-        'cookie setting, redirects, etc.',
-    ),
-  code_pointers: z
-    .string()
-    .min(1)
-    .describe(
-      'Pointers to the primary files and functions in the codebase that manage authentication and ' + 'session logic.',
-    ),
-});
-
-const RoleAssignmentSchema = z.object({
-  role_determination: z
-    .string()
-    .min(1)
-    .describe('How roles are assigned post-authentication — database lookup, JWT claims, external service, etc.'),
-  default_role: z.string().min(1).describe('What role new users get by default.'),
-  role_upgrade_path: z
-    .string()
-    .min(1)
-    .describe(
-      'How users can gain higher privileges — admin approval, self-service, automatic, etc. ' +
-        'If no upgrade path exists, state that.',
-    ),
-  code_implementation: z
-    .string()
-    .min(1)
-    .describe('Where role assignment logic is implemented (file paths and functions).'),
-});
-
-const PrivilegeStorageSchema = z.object({
-  storage_location: z
-    .string()
-    .min(1)
-    .describe('Where user privileges are stored — JWT claims, session data, database, external service.'),
-  validation_points: z.string().min(1).describe('Where role checks happen — middleware, decorators, inline checks.'),
-  cache_session_persistence: z.string().min(1).describe('How long privileges are cached, and when they are refreshed.'),
-  code_pointers: z.string().min(1).describe('Files that handle privilege validation.'),
-});
-
-const RoleSwitchingImpersonationSchema = z.object({
-  applicable: z
-    .boolean()
-    .describe(
-      'False only if the application has no impersonation, sudo-mode, or role-switching features ' +
-        'at all. When false, the other fields in this object may be null.',
-    ),
-  impersonation_features: z
-    .string()
-    .nullable()
-    .describe(
-      'Any ability for admins or higher-privilege users to impersonate other users. Pass null when ' +
-        'applicable is false.',
-    ),
-  role_switching: z
-    .string()
-    .nullable()
-    .describe('Temporary privilege elevation mechanisms like "sudo mode". Pass null when applicable is false.'),
-  audit_trail: z
-    .string()
-    .nullable()
-    .describe(
-      'Whether role switches or impersonation events are logged, and where. Pass null when applicable is false.',
-    ),
-  code_implementation: z
-    .string()
-    .nullable()
-    .describe('Where these features are implemented (file paths and functions). Pass null when applicable is false.'),
-});
-
-export const AuthenticationInputSchema = z.object({
-  session_flow: SessionFlowSchema.describe(
-    'Authentication & Session Management Flow — overall entry points, mechanism, and code pointers. ' +
-      'Becomes Section 3 of the rendered deliverable.',
-  ),
-  role_assignment: RoleAssignmentSchema.describe(
-    'Role Assignment Process — how roles are determined post-authentication. ' + 'Becomes Section 3.1.',
-  ),
-  privilege_storage: PrivilegeStorageSchema.describe(
-    'Privilege Storage & Validation — where privileges live and where they are checked. ' + 'Becomes Section 3.2.',
-  ),
-  role_switching_impersonation: RoleSwitchingImpersonationSchema.describe(
-    'Role Switching & Impersonation — impersonation, sudo mode, audit trails. Becomes Section 3.3. ' +
-      'Set applicable=false if no such features exist; the other fields may be null in that case.',
-  ),
-});
-
-const HTTP_METHOD_VALUES = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'OPTIONS', 'HEAD', 'WS'] as const;
-
-const EndpointSchema = z.object({
-  method: z.enum(HTTP_METHOD_VALUES).describe('HTTP method. Use WS for WebSocket upgrade endpoints.'),
-  path: z.string().min(1).describe('Endpoint path with parameter placeholders, e.g. "/api/users/{user_id}".'),
-  required_role: z.string().min(1).describe('Minimum role needed (anon, user, admin, etc.).'),
-  object_id_parameters: z
-    .array(z.string())
-    .describe('Parameters that identify specific objects (user_id, order_id, etc.). Empty array if none.'),
-  authorization_mechanism: z
-    .string()
-    .min(1)
-    .describe(
-      'How access is controlled — middleware, decorator, inline check. ' +
-        'E.g. "Bearer Token + ownership check", "requireAuth() + requireAdmin()", "None".',
-    ),
-  description: z.string().min(1).describe("Brief description of the endpoint's purpose."),
-  code_pointer: z
-    .string()
-    .min(1)
-    .describe('File path and (where possible) line number of the handler. E.g. "auth.controller.ts:45".'),
-});
-
-export const AddEndpointsInputSchema = z.object({
-  endpoints: z
-    .array(EndpointSchema)
-    .describe(
-      'A batch of network-accessible API endpoints to append to the catalog. Include only endpoints ' +
-        'reachable through the deployed application — exclude CLI tools, dev-only routes, build scripts. ' +
-        'Duplicate (method, path) pairs across calls are skipped as no-ops; the response reports which ' +
-        'were added vs. skipped.',
-    ),
-});
-
-export const InputVectorsInputSchema = z.object({
-  url_parameters: z
-    .array(z.string().min(1))
-    .describe(
-      'URL parameter input vectors — each entry should identify the parameter and (where possible) ' +
-        'the file:line of the handler. E.g. "?redirect_url= @ auth.controller.ts:88".',
-    ),
-  post_body_fields: z
-    .array(z.string().min(1))
-    .describe(
-      'POST/PUT body field input vectors (JSON or form). E.g. "username @ login.handler.ts:34", ' +
-        '"profile.description @ users.controller.ts:120".',
-    ),
-  http_headers: z
-    .array(z.string().min(1))
-    .describe(
-      'HTTP header input vectors. Include both standard headers consumed by app code (e.g., ' +
-        'X-Forwarded-For) and custom application headers.',
-    ),
-  cookie_values: z
-    .array(z.string().min(1))
-    .describe('Cookie-based input vectors. E.g. "preferences_cookie @ middleware/prefs.ts:22".'),
-});
-
-const ENTITY_TYPE_VALUES = ['ExternAsset', 'Service', 'Identity', 'DataStore', 'AdminPlane', 'ThirdParty'] as const;
-
-const ENTITY_ZONE_VALUES = ['Internet', 'Edge', 'App', 'Data', 'Admin', 'BuildCI', 'ThirdParty'] as const;
-
-const DATA_LABEL_VALUES = ['PII', 'Tokens', 'Payments', 'Secrets', 'Public'] as const;
-
-const FLOW_CHANNEL_VALUES = ['HTTP', 'HTTPS', 'TCP', 'Message', 'File', 'Token'] as const;
-
-const GUARD_CATEGORY_VALUES = [
-  'Auth',
-  'Network',
-  'Protocol',
-  'Env',
-  'RateLimit',
-  'Authorization',
-  'ObjectOwnership',
-] as const;
-
-const EntityMetadataPairSchema = z.object({
-  key: z.string().min(1).describe('Metadata key (e.g., "Hosts", "Endpoints", "Engine", "Issuer").'),
-  value: z.string().min(1).describe('Metadata value for this key.'),
-});
-
-const EntitySchema = z.object({
-  title: z
-    .string()
-    .min(1)
-    .describe('Unique short name for the entity (e.g., "ExampleWebApp", "PostgreSQL-DB", "IdentityProvider").'),
-  type: z
-    .enum(ENTITY_TYPE_VALUES)
-    .describe(
-      'Entity type. ExternAsset = client-side asset; Service = backend service; Identity = identity ' +
-        'provider; DataStore = database / cache / object store; AdminPlane = admin/control surface; ' +
-        'ThirdParty = external integration.',
-    ),
-  zone: z
-    .enum(ENTITY_ZONE_VALUES)
-    .describe(
-      'Trust zone. Internet = public; Edge = CDN/WAF/reverse-proxy tier; App = application/business logic; ' +
-        'Data = persistent storage; Admin = administrative surface; BuildCI = build/CI/CD infrastructure; ' +
-        'ThirdParty = external trust domain.',
-    ),
-  tech: z
-    .string()
-    .min(1)
-    .describe('Short technology/framework description (e.g., "Node/Express", "Postgres 14", "AWS S3").'),
-  data: z
-    .array(z.enum(DATA_LABEL_VALUES))
-    .describe('Data labels handled by this entity. Empty array if the entity handles only Public data.'),
-  notes: z
-    .string()
-    .describe('Freeform context (e.g., "public-facing", "stores sensitive user data"). Empty string if none.'),
-  metadata: z
-    .array(EntityMetadataPairSchema)
-    .describe(
-      'Ordered key/value pairs of technical metadata for this entity. Becomes the Section 6.2 row ' +
-        'rendered as "Key: Value; Key: Value; …". Example pairs for a service: Hosts, Endpoints, Auth, ' +
-        'Dependencies; for a datastore: Engine, Exposure, Consumers, Credentials.',
-    ),
-});
-
-const FlowSchema = z.object({
-  from: z.string().min(1).describe('Source entity title — must match a title from the entities array.'),
-  to: z.string().min(1).describe('Destination entity title — must match a title from the entities array.'),
-  channel: z.enum(FLOW_CHANNEL_VALUES).describe('Transport channel for this flow.'),
-  path_port: z
-    .string()
-    .min(1)
-    .describe('Path and/or port for this flow. E.g. ":443 /api/users/me", ":5432", "queue: orders".'),
-  guards: z
-    .array(z.string().min(1))
-    .describe(
-      'Guard names that gate this flow. Each should match a name from the guards array. Empty array ' +
-        'means no guards apply (publicly accessible).',
-    ),
-  touches: z
-    .array(z.enum(DATA_LABEL_VALUES))
-    .describe('Data labels this flow carries. Empty array if only Public data flows.'),
-});
-
-const GuardSchema = z.object({
-  name: z.string().min(1).describe('Short guard identifier (e.g., "auth:user", "ownership:user", "vpc-only", "mtls").'),
-  category: z
-    .enum(GUARD_CATEGORY_VALUES)
-    .describe(
-      'Guard category. Auth = authentication identity; Authorization = role/scope check; ' +
-        'ObjectOwnership = ownership-based check; Network = network-level restriction; ' +
-        'Protocol = protocol-level requirement; Env = environment-bound restriction; ' +
-        'RateLimit = throttling.',
-    ),
-  statement: z.string().min(1).describe('One-sentence description of what this guard enforces.'),
-});
-
-export const NetworkMapInputSchema = z.object({
-  entities: z
-    .array(EntitySchema)
-    .describe(
-      'All major components of the system. Becomes Section 6.1 (Entities) and Section 6.2 ' +
-        '(Entity Metadata, split per-entity from the metadata field).',
-    ),
-  flows: z
-    .array(FlowSchema)
-    .describe(
-      'How entities communicate. Becomes Section 6.3. The from/to fields cross-reference entities ' +
-        'by title; the guards field cross-references guards by name.',
-    ),
-  guards: z.array(GuardSchema).describe('Catalog of guards referenced by flows. Becomes Section 6.4.'),
-});
-
-const RoleSchema = z.object({
-  name: z.string().min(1).describe('Role name (e.g., "anon", "user", "admin", "team_admin").'),
-  privilege_level: z
-    .number()
-    .int()
-    .min(0)
-    .max(10)
-    .describe('Privilege rank from 0 (lowest, anonymous) to 10 (highest, full admin).'),
-  scope_domain: z.string().min(1).describe('Scope of this role: Global, Org, Team, Project, etc.'),
-  code_implementation: z
-    .string()
-    .min(1)
-    .describe('Where this role is defined or checked (middleware, decorator, file:line, etc.).'),
-  default_landing_page: z
-    .string()
-    .min(1)
-    .describe('Default landing page or route after authentication. Use "N/A" for roles without a UI.'),
-  accessible_route_patterns: z
-    .array(z.string().min(1))
-    .describe('Route patterns this role can access. Empty array if the role has no UI access.'),
-  authentication_method: z
-    .string()
-    .min(1)
-    .describe('How this role authenticates: "None" (anon), "Session/JWT", "Session/JWT + role claim", etc.'),
-  middleware_guards: z
-    .string()
-    .min(1)
-    .describe('Middleware and guards that enforce this role (e.g., "requireAuth() + requireAdmin()").'),
-  permission_checks: z
-    .string()
-    .min(1)
-    .describe('How permission checks are expressed in code (e.g., "req.user.role === \'admin\'").'),
-  storage_location: z
-    .string()
-    .min(1)
-    .describe('Where this role is stored at runtime (JWT claims, session data, etc.).'),
-});
-
-const PrivilegeLatticeSchema = z.object({
-  ordering_diagram: z
-    .string()
-    .min(1)
-    .describe(
-      'ASCII diagram showing role ordering. Use → for "can access resources of". ' + 'E.g. "anon → user → admin".',
-    ),
-  parallel_isolation_notes: z
-    .string()
-    .describe(
-      'Notes on parallel isolation between roles using ||. E.g. "team_admin || dept_admin (both > user, ' +
-        'but isolated from each other)". Empty string if no parallel isolation exists.',
-    ),
-  role_switching_notes: z
-    .string()
-    .nullable()
-    .optional()
-    .describe(
-      'Optional pointer to impersonation, sudo mode, or role-switching mechanisms documented in ' +
-        'set_authentication.role_switching_impersonation. Null/omitted if no such mechanisms exist.',
-    ),
-});
-
-export const RoleArchitectureInputSchema = z.object({
-  roles: z
-    .array(RoleSchema)
-    .describe(
-      'All distinct privilege levels found in the application. Becomes Sections 7.1 (Discovered Roles), ' +
-        '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping), split by the renderer per-role.',
-    ),
-  privilege_lattice: PrivilegeLatticeSchema.describe(
-    'The role hierarchy showing dominance and parallel isolation. Becomes Section 7.2.',
-  ),
-});
-
-const PRIORITY_VALUES = ['High', 'Medium', 'Low'] as const;
-
-const HorizontalCandidateSchema = z.object({
-  priority: z
-    .enum(PRIORITY_VALUES)
-    .describe('Priority: High, Medium, or Low, based on data sensitivity (title-case literals).'),
-  endpoint_pattern: z
-    .string()
-    .min(1)
-    .describe('Endpoint pattern with the object identifier. E.g. "/api/orders/{order_id}".'),
-  object_id_parameter: z
-    .string()
-    .min(1)
-    .describe('The parameter name that identifies the target object (e.g., "order_id", "user_id").'),
-  data_type: z.string().min(1).describe('Type of data exposed: user_data, financial, admin_config, user_files, etc.'),
-  sensitivity: z
-    .string()
-    .min(1)
-    .describe('One-line description of what is at risk (e.g., "User can access other users\' orders").'),
-});
-
-const VerticalCandidateSchema = z.object({
-  target_role: z.string().min(1).describe('Role required to access this endpoint (the role being escalated to).'),
-  endpoint_pattern: z
-    .string()
-    .min(1)
-    .describe('Endpoint pattern that requires elevated privileges. E.g. "/admin/*", "/api/admin/users".'),
-  functionality: z
-    .string()
-    .min(1)
-    .describe('What the endpoint does (e.g., "Administrative functions", "User management").'),
-  risk_level: z.enum(PRIORITY_VALUES).describe('Risk level: High, Medium, or Low (title-case literals).'),
-});
-
-const ContextCandidateSchema = z.object({
-  workflow: z.string().min(1).describe('Multi-step workflow name (e.g., "Checkout", "Onboarding", "Password Reset").'),
-  endpoint: z.string().min(1).describe('Endpoint that assumes a prior workflow state. E.g. "/api/checkout/confirm".'),
-  expected_prior_state: z.string().min(1).describe('What state should already exist before this endpoint is called.'),
-  bypass_potential: z.string().min(1).describe('What an attacker could achieve by skipping the prior state.'),
-});
-
-export const AuthzCandidatesInputSchema = z.object({
-  horizontal: z
-    .array(HorizontalCandidateSchema)
-    .describe(
-      "Endpoints with object identifiers that could allow horizontal access to other users' " +
-        'resources. Becomes Section 8.1. The renderer assigns stable AUTHZ-CAND-NN IDs.',
-    ),
-  vertical: z
-    .array(VerticalCandidateSchema)
-    .describe(
-      'Endpoints that require higher privileges and could be targets for vertical escalation. ' +
-        'Becomes Section 8.2. Exclude endpoints intentionally shared across roles.',
-    ),
-  context: z
-    .array(ContextCandidateSchema)
-    .describe('Multi-step workflow endpoints that assume prior steps were completed. Becomes Section 8.3.'),
-});
-
-export const InjectionSourcesInputSchema = z.object({
-  applicable: z
-    .boolean()
-    .describe(
-      'False only if the application has no network-accessible code paths reaching dangerous sinks ' +
-        'at all. Otherwise true, even if no sources were found in a given category — empty arrays mean ' +
-        '"scanned this category, no sources found".',
-    ),
-  command_injection: z
-    .array(SinkRefSchema)
-    .describe(
-      'Command injection sources: data flowing from a user-controlled origin into a program variable ' +
-        'that is eventually interpolated into a shell or system command string (within network-accessible ' +
-        'code paths).',
-    ),
-  sql_injection: z
-    .array(SinkRefSchema)
-    .describe(
-      'SQL injection sources: user-controllable input that reaches a database query string (within ' +
-        'network-accessible code paths).',
-    ),
-  lfi_rfi: z
-    .array(SinkRefSchema)
-    .describe(
-      'Local/Remote File Inclusion sources: user-controllable input passed to include/require/load ' +
-        'functions that resolve to filesystem or remote paths (within network-accessible code paths).',
-    ),
-  path_traversal: z
-    .array(SinkRefSchema)
-    .describe(
-      'Path traversal sources: user-controllable input that influences file paths in read/write ' +
-        'operations (fopen, readFile, etc.) within network-accessible code paths.',
-    ),
-  ssti: z
-    .array(SinkRefSchema)
-    .describe(
-      'Server-Side Template Injection sources: user-controllable input embedded in template ' +
-        'expressions or template content within network-accessible code paths.',
-    ),
-  deserialization: z
-    .array(SinkRefSchema)
-    .describe(
-      'Insecure deserialization sources: user-controllable input passed to deserialization functions ' +
-        'within network-accessible code paths.',
-    ),
-});
-
-// ============================================================================
-// EXPORTED TYPES
-// ============================================================================
-
-export type ExecutiveSummaryInput = z.infer<typeof ExecutiveSummaryInputSchema>;
-export type TechnologyStackInput = z.infer<typeof TechnologyStackInputSchema>;
-export type AuthenticationInput = z.infer<typeof AuthenticationInputSchema>;
-export type AddEndpointsInput = z.infer<typeof AddEndpointsInputSchema>;
-export type Endpoint = z.infer<typeof EndpointSchema>;
-export type InputVectorsInput = z.infer<typeof InputVectorsInputSchema>;
-export type NetworkMapInput = z.infer<typeof NetworkMapInputSchema>;
-export type Entity = z.infer<typeof EntitySchema>;
-export type Flow = z.infer<typeof FlowSchema>;
-export type Guard = z.infer<typeof GuardSchema>;
-export type RoleArchitectureInput = z.infer<typeof RoleArchitectureInputSchema>;
-export type Role = z.infer<typeof RoleSchema>;
-export type PrivilegeLattice = z.infer<typeof PrivilegeLatticeSchema>;
-export type AuthzCandidatesInput = z.infer<typeof AuthzCandidatesInputSchema>;
-export type HorizontalCandidate = z.infer<typeof HorizontalCandidateSchema>;
-export type VerticalCandidate = z.infer<typeof VerticalCandidateSchema>;
-export type ContextCandidate = z.infer<typeof ContextCandidateSchema>;
-export type InjectionSourcesInput = z.infer<typeof InjectionSourcesInputSchema>;
-export type Priority = (typeof PRIORITY_VALUES)[number];
-
-export interface ReconData {
-  readonly executive_summary?: ExecutiveSummaryInput;
-  readonly technology_stack?: TechnologyStackInput;
-  readonly authentication?: AuthenticationInput;
-  readonly endpoints?: readonly Endpoint[];
-  readonly input_vectors?: InputVectorsInput;
-  readonly network_map?: NetworkMapInput;
-  readonly role_architecture?: RoleArchitectureInput;
-  readonly authz_candidates?: AuthzCandidatesInput;
-  readonly injection_sources?: InjectionSourcesInput;
-}
-
-export const RECON_ONE_SHOT_TOOLS = [
-  'set_executive_summary',
-  'set_technology_stack',
-  'set_authentication',
-  'set_input_vectors',
-  'set_network_map',
-  'set_role_architecture',
-  'set_authz_candidates',
-  'set_injection_sources',
-] as const;
-
-export type ReconOneShotToolName = (typeof RECON_ONE_SHOT_TOOLS)[number];
-
-export type ReconToolStatus = 'called' | 'skipped';
-
-export interface ReconCallStatus {
-  readonly set_executive_summary: ReconToolStatus;
-  readonly set_technology_stack: ReconToolStatus;
-  readonly set_authentication: ReconToolStatus;
-  readonly add_endpoints: { readonly calls: number; readonly endpoints_seen: number };
-  readonly set_input_vectors: ReconToolStatus;
-  readonly set_network_map: ReconToolStatus;
-  readonly set_role_architecture: ReconToolStatus;
-  readonly set_authz_candidates: ReconToolStatus;
-  readonly set_injection_sources: ReconToolStatus;
-}
-
-// ============================================================================
-// RESPONSE HELPERS
-// ============================================================================
-
-interface ToolResult {
-  [x: string]: unknown;
-  content: Array<{ type: 'text'; text: string }>;
-  isError: boolean;
-}
-
-function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
-  return {
-    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
-    isError: response.status === 'error',
-  };
-}
-
-function successResult(data: Record<string, unknown>): ToolResult {
-  return createToolResult({ status: 'success', ...data });
-}
-
-function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
-  return createToolResult({ status: 'error', message, errorType, retryable });
-}
-
-function endpointKey(method: string, path: string): string {
-  return `${method} ${path}`;
-}
-
-// ============================================================================
-// SERVER FACTORY
-// ============================================================================
-
-export interface ReconCollectorServer {
-  server: McpSdkServerConfigWithInstance;
-  getAll(): ReconData;
-  getCallStatus(): ReconCallStatus;
-}
-
-export function createReconCollectorServer(): ReconCollectorServer {
-  const state: {
-    executive_summary?: ExecutiveSummaryInput;
-    technology_stack?: TechnologyStackInput;
-    authentication?: AuthenticationInput;
-    input_vectors?: InputVectorsInput;
-    network_map?: NetworkMapInput;
-    role_architecture?: RoleArchitectureInput;
-    authz_candidates?: AuthzCandidatesInput;
-    injection_sources?: InjectionSourcesInput;
-  } = {};
-
-  const endpoints: Endpoint[] = [];
-  const seenEndpointKeys = new Set<string>();
-  let addEndpointsCalls = 0;
-
-  function alreadyCalled(toolName: ReconOneShotToolName): ToolResult {
-    return errorResult(
-      `${toolName} has already been called. Each set_* tool may only be called once per run.`,
-      'DuplicateError',
-      false,
-    );
-  }
-
-  const setExecutiveSummary = tool(
-    'set_executive_summary',
-    "Record the application's executive summary: purpose, core technology stack, and primary " +
-      'user-facing components. Call exactly once before terminating. Becomes Section 1 of the rendered ' +
-      'deliverable. Duplicate calls are rejected.',
-    ExecutiveSummaryInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.executive_summary) return alreadyCalled('set_executive_summary');
-      state.executive_summary = input;
-      return successResult({ set: 'set_executive_summary' });
-    },
-  );
-
-  const setTechnologyStack = tool(
-    'set_technology_stack',
-    'Record the technology and service map: frontend, backend, and infrastructure. Call exactly once ' +
-      'before terminating. Becomes Section 2 of the rendered deliverable. Duplicate calls are rejected.',
-    TechnologyStackInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.technology_stack) return alreadyCalled('set_technology_stack');
-      state.technology_stack = input;
-      return successResult({ set: 'set_technology_stack' });
-    },
-  );
-
-  const setAuthentication = tool(
-    'set_authentication',
-    'Record the authentication and session management architecture: session flow, role assignment, ' +
-      'privilege storage, and role switching/impersonation. Call exactly once before terminating. ' +
-      'Becomes Sections 3, 3.1, 3.2, and 3.3 of the rendered deliverable. Set ' +
-      'role_switching_impersonation.applicable=false (with the other fields null) if no such features ' +
-      'exist. Duplicate calls are rejected.',
-    AuthenticationInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.authentication) return alreadyCalled('set_authentication');
-      state.authentication = input;
-      return successResult({ set: 'set_authentication' });
-    },
-  );
-
-  const addEndpoints = tool(
-    'add_endpoints',
-    'Append a batch of network-accessible API endpoints to the catalog. May be called multiple times — ' +
-      'each call appends. Use a single call for small inventories, or split across 2-3 calls for large ' +
-      'inventories (50+ endpoints) to keep individual payloads comfortable. Duplicate (method, path) ' +
-      'pairs across calls are skipped as no-ops; the response reports added vs. skipped. Becomes ' +
-      'Section 4 of the rendered deliverable and drives vuln-authz / vuln-injection todos downstream. ' +
-      'The renderer sorts by (path, method) before rendering, so emission order does not affect output.',
-    AddEndpointsInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      addEndpointsCalls += 1;
-      const added: string[] = [];
-      const skipped: string[] = [];
-      for (const ep of input.endpoints) {
-        const key = endpointKey(ep.method, ep.path);
-        if (seenEndpointKeys.has(key)) {
-          skipped.push(key);
-          continue;
-        }
-        seenEndpointKeys.add(key);
-        endpoints.push(ep);
-        added.push(key);
-      }
-      return successResult({
-        set: 'add_endpoints',
-        added: added.length,
-        duplicates_skipped: skipped,
-        total_accumulated: endpoints.length,
-      });
-    },
-  );
-
-  const setInputVectors = tool(
-    'set_input_vectors',
-    'Record potential input vectors grouped by source: URL parameters, POST body fields, HTTP headers, ' +
-      'and cookie values. Call exactly once before terminating. Becomes Section 5 of the rendered ' +
-      'deliverable. Drives downstream vulnerability analysis. Duplicate calls are rejected.',
-    InputVectorsInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.input_vectors) return alreadyCalled('set_input_vectors');
-      state.input_vectors = input;
-      return successResult({ set: 'set_input_vectors' });
-    },
-  );
-
-  const setNetworkMap = tool(
-    'set_network_map',
-    'Record the network and interaction map: entities, flows, and guards. Call exactly once before ' +
-      'terminating. Becomes Sections 6.1 (Entities), 6.2 (Entity Metadata), 6.3 (Flows), and 6.4 ' +
-      '(Guards Directory) of the rendered deliverable. The renderer splits the entities array into ' +
-      'the 6.1 and 6.2 tables and sorts each array deterministically. Duplicate calls are rejected.',
-    NetworkMapInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.network_map) return alreadyCalled('set_network_map');
-      state.network_map = input;
-      return successResult({ set: 'set_network_map' });
-    },
-  );
-
-  const setRoleArchitecture = tool(
-    'set_role_architecture',
-    'Record the role and privilege architecture: discovered roles and the privilege lattice. Call ' +
-      'exactly once before terminating. Becomes Sections 7.1 (Discovered Roles), 7.2 (Privilege Lattice), ' +
-      '7.3 (Role Entry Points), and 7.4 (Role-to-Code Mapping) of the rendered deliverable. The renderer ' +
-      'splits the roles array into the per-section tables. Duplicate calls are rejected.',
-    RoleArchitectureInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.role_architecture) return alreadyCalled('set_role_architecture');
-      state.role_architecture = input;
-      return successResult({ set: 'set_role_architecture' });
-    },
-  );
-
-  const setAuthzCandidates = tool(
-    'set_authz_candidates',
-    'Record authorization vulnerability candidates: horizontal escalation, vertical escalation, and ' +
-      'context-based candidates. Call exactly once before terminating. Becomes Sections 8.1, 8.2, and ' +
-      '8.3 of the rendered deliverable. The renderer assigns stable AUTHZ-CAND-NN IDs across the three ' +
-      'sub-arrays in horizontal → vertical → context order, which vuln-authz reads as its todo list. ' +
-      'Duplicate calls are rejected.',
-    AuthzCandidatesInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.authz_candidates) return alreadyCalled('set_authz_candidates');
-      state.authz_candidates = input;
-      return successResult({ set: 'set_authz_candidates' });
-    },
-  );
-
-  const setInjectionSources = tool(
-    'set_injection_sources',
-    'Record discovered injection sources grouped by vulnerability class. Call exactly once before ' +
-      'terminating. If the application has no network-accessible code paths to dangerous sinks, set ' +
-      'applicable=false; otherwise populate each category array (empty arrays mean "scanned, no sources ' +
-      'of this kind"). Becomes Section 9 of the rendered deliverable. Drives the vuln-injection agent\'s ' +
-      'todos downstream. Duplicate calls are rejected.',
-    InjectionSourcesInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.injection_sources) return alreadyCalled('set_injection_sources');
-      state.injection_sources = input;
-      return successResult({ set: 'set_injection_sources' });
-    },
-  );
-
-  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
-    name: 'recon-collector',
-    version: '1.0.0',
-    tools: [
-      setExecutiveSummary,
-      setTechnologyStack,
-      setAuthentication,
-      addEndpoints,
-      setInputVectors,
-      setNetworkMap,
-      setRoleArchitecture,
-      setAuthzCandidates,
-      setInjectionSources,
-    ],
-  });
-
-  function statusOf<K extends ReconOneShotToolName>(key: K): ReconToolStatus {
-    const flagMap: Record<ReconOneShotToolName, unknown> = {
-      set_executive_summary: state.executive_summary,
-      set_technology_stack: state.technology_stack,
-      set_authentication: state.authentication,
-      set_input_vectors: state.input_vectors,
-      set_network_map: state.network_map,
-      set_role_architecture: state.role_architecture,
-      set_authz_candidates: state.authz_candidates,
-      set_injection_sources: state.injection_sources,
-    };
-    return flagMap[key] ? 'called' : 'skipped';
-  }
-
-  return {
-    server,
-    getAll: (): ReconData => ({
-      ...(state.executive_summary && { executive_summary: state.executive_summary }),
-      ...(state.technology_stack && { technology_stack: state.technology_stack }),
-      ...(state.authentication && { authentication: state.authentication }),
-      ...(endpoints.length > 0 && { endpoints }),
-      ...(state.input_vectors && { input_vectors: state.input_vectors }),
-      ...(state.network_map && { network_map: state.network_map }),
-      ...(state.role_architecture && { role_architecture: state.role_architecture }),
-      ...(state.authz_candidates && { authz_candidates: state.authz_candidates }),
-      ...(state.injection_sources && { injection_sources: state.injection_sources }),
-    }),
-    getCallStatus: (): ReconCallStatus => ({
-      set_executive_summary: statusOf('set_executive_summary'),
-      set_technology_stack: statusOf('set_technology_stack'),
-      set_authentication: statusOf('set_authentication'),
-      add_endpoints: { calls: addEndpointsCalls, endpoints_seen: endpoints.length },
-      set_input_vectors: statusOf('set_input_vectors'),
-      set_network_map: statusOf('set_network_map'),
-      set_role_architecture: statusOf('set_role_architecture'),
-      set_authz_candidates: statusOf('set_authz_candidates'),
-      set_injection_sources: statusOf('set_injection_sources'),
-    }),
-  };
-}
-
-// Re-exported here so the renderer can import the shared sink type without
-// depending on pre-recon's collector by name.
-export type { SinkRef };

apps/worker/src/mcp-server/vuln-collector.ts

@@ -1,512 +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.
-
-/**
- * Vuln Collector MCP Server (factory parameterized by vulnerability class).
- *
- * Exposes 4 one-shot, Zod-validated MCP tools per vuln agent (injection, xss,
- * auth, ssrf, authz) that feed a deterministic renderer producing
- * {class}_analysis_deliverable.md:
- *   - set_findings_summary       — §1 executive summary + §2 dominant patterns
- *   - set_strategic_intelligence — §3, per-class schema
- *   - set_safe_vectors           — §4, shared schema across classes
- *   - set_blind_spots            — §5, shared schema across classes
- *
- * Only set_strategic_intelligence varies by class; the collector branches on
- * vulnClass to assemble the right schema. The other 3 tools are identical
- * across classes.
- *
- * Skipped tools surface as renderer placeholders, not activity failures.
- * getCallStatus() exposes the per-run call pattern for logging. Each Zod
- * schema's field-level descriptions carry the section guidance, so the SDK
- * injects it into the agent's tool catalog.
- */
-
-import type { McpSdkServerConfigWithInstance } from '@anthropic-ai/claude-agent-sdk';
-import { createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
-import { type ZodRawShape, z } from 'zod';
-
-// ============================================================================
-// CLASS DISCRIMINATOR
-// ============================================================================
-
-export const VULN_CLASSES = ['injection', 'xss', 'auth', 'ssrf', 'authz'] as const;
-export type VulnClass = (typeof VULN_CLASSES)[number];
-
-// Classes whose deliverables carry a Section 5 (blind spots). The auth and ssrf
-// analyses have no blind-spots section, so the set_blind_spots tool is withheld
-// from those agents and the renderer omits the section. Single source of truth
-// for both the tool registration and the rendering gate.
-export const BLIND_SPOTS_CLASSES: ReadonlySet<VulnClass> = new Set<VulnClass>(['injection', 'xss', 'authz']);
-
-// ============================================================================
-// SHARED SCHEMAS — set_findings_summary, set_safe_vectors, set_blind_spots
-// ============================================================================
-
-const PatternSchema = z.object({
-  name: z
-    .string()
-    .min(1)
-    .describe(
-      'Concise pattern name, e.g. "Weak Session Management", "Reflected XSS in Search Parameter", ' +
-        '"Insufficient URL Validation".',
-    ),
-  description: z.string().min(1).describe('One- to two-sentence description of the pattern observed in the codebase.'),
-  implication: z
-    .string()
-    .min(1)
-    .describe('One- to two-sentence implication for exploitation — what does this pattern enable an attacker to do.'),
-  representative_finding_ids: z
-    .array(z.string().min(1))
-    .min(1)
-    .describe(
-      'IDs of findings that exhibit this pattern (e.g. ["AUTH-VULN-01", "AUTH-VULN-02"]). Must match ' +
-        'IDs the agent has assigned in the structured-output exploitation queue.',
-    ),
-});
-
-export const FindingsSummaryInputSchema = z.object({
-  key_outcome: z
-    .string()
-    .min(1)
-    .describe(
-      'One to two sentences capturing the headline result of your analysis — what was found and its ' +
-        'severity profile (e.g. "Several high-confidence SQL injection vulnerabilities were identified; ' +
-        'all findings have been passed to the exploitation phase"). Becomes Section 1 of the rendered ' +
-        'deliverable.',
-    ),
-  patterns: z
-    .array(PatternSchema)
-    .describe(
-      'Complete list of dominant patterns observed across findings. Pass all patterns in one call. ' +
-        'Empty array is acceptable if no recurring patterns were observed — the deliverable will render ' +
-        '"No dominant patterns identified" for Section 2 in that case.',
-    ),
-});
-
-export const SafeVectorInputSchema = z.object({
-  subject: z
-    .string()
-    .min(1)
-    .describe(
-      'The specific subject of analysis. For injection/xss runs, the input parameter name (e.g. ' +
-        '"username", "redirect_url"). For auth/ssrf runs, the component or flow name (e.g. ' +
-        '"Password Hashing", "Webhook Configuration"). For authz runs, the endpoint (e.g. ' +
-        '"POST /api/auth/logout"). The renderer maps this to the class-appropriate column header.',
-    ),
-  location: z
-    .string()
-    .min(1)
-    .describe(
-      'File path with line number (e.g. "controllers/authController.js:45") or endpoint URL (e.g. ' +
-        '"/profile"). For authz runs, this is the guard location specifically (e.g. ' +
-        '"middleware/auth.js:45"). The renderer maps this to the class-appropriate column header.',
-    ),
-  defense_mechanism: z
-    .string()
-    .min(1)
-    .describe(
-      'The robust defense observed (e.g. "Prepared Statement (Parameter Binding)", "HTML Entity ' +
-        'Encoding", "Strict URL Whitelist Validation", "bcrypt.compare for constant-time check").',
-    ),
-  render_context: z
-    .string()
-    .nullable()
-    .optional()
-    .describe(
-      'XSS-only: the DOM render context for the validated vector — one of HTML_BODY, HTML_ATTRIBUTE, ' +
-        'JAVASCRIPT_STRING, URL_PARAM, CSS_VALUE. Omit (or pass null) for non-XSS classes; the renderer ' +
-        'only emits this column for the XSS deliverable.',
-    ),
-});
-
-export const SafeVectorsInputSchema = z.object({
-  vectors: z
-    .array(SafeVectorInputSchema)
-    .describe(
-      'All input vectors / components / endpoints that were analyzed and confirmed to have robust, ' +
-        'context-appropriate defenses. Empty array is acceptable but unusual — the deliverable will ' +
-        'render "No vectors confirmed secure during analysis" for Section 4 in that case. Becomes ' +
-        'Section 4 of the rendered deliverable. The renderer sorts by (subject, location) before ' +
-        'rendering, so emission order does not affect output.',
-    ),
-});
-
-export const BlindSpotItemSchema = z.object({
-  heading: z
-    .string()
-    .min(1)
-    .describe(
-      'Short heading for the blind spot (e.g. "Untraced Asynchronous Flows", ' +
-        '"Limited Visibility into Stored Procedures", "Minified JavaScript Bundle").',
-    ),
-  description: z
-    .string()
-    .min(1)
-    .describe(
-      'One to three sentences describing the analysis gap — what could not be traced, why, and what ' +
-        'the residual risk is.',
-    ),
-});
-
-export const BlindSpotsInputSchema = z.object({
-  items: z
-    .array(BlindSpotItemSchema)
-    .describe(
-      'Analysis constraints, untraced code paths, or other coverage gaps that should be noted. ' +
-        'Empty array is acceptable on high-coverage runs — the deliverable will render "No analysis ' +
-        'constraints or blind spots identified" for Section 5 in that case. Becomes Section 5 of the ' +
-        'rendered deliverable.',
-    ),
-});
-
-// ============================================================================
-// PER-CLASS set_strategic_intelligence SCHEMAS (flat — no nesting)
-// ============================================================================
-
-const InjectionStrategicIntelSchema = z.object({
-  defensive_evasion_waf: z
-    .string()
-    .min(1)
-    .describe(
-      'WAF behavior observed during analysis: active rules, common payloads blocked, identified ' +
-        'bypasses (e.g. "WAF blocks UNION SELECT but not time-based blind injection"). Write ' +
-        '"Not applicable — no WAF observed" if none was detected.',
-    ),
-  error_based_potential: z
-    .string()
-    .min(1)
-    .describe(
-      'Whether endpoints leak verbose database errors that enable error-based injection (e.g. ' +
-        '"/api/products returns verbose PostgreSQL error messages, prime target for error-based ' +
-        'exploitation"). Write "Not applicable" if no injection findings exist.',
-    ),
-  confirmed_database_technology: z
-    .string()
-    .min(1)
-    .describe(
-      'Database engine(s) confirmed via error syntax or function calls (e.g. "PostgreSQL, confirmed ' +
-        'via pg_sleep() and verbose error syntax"). Drives payload selection downstream. Write ' +
-        '"Not applicable" if no DB sinks in scope.',
-    ),
-});
-
-const XssStrategicIntelSchema = z.object({
-  csp_analysis: z
-    .string()
-    .min(1)
-    .describe(
-      'Content Security Policy observed and its bypassability: current policy text, critical bypasses ' +
-        "(e.g. \"script-src 'self' https://trusted-cdn.com — the trusted CDN hosts vulnerable AngularJS, " +
-        'enabling client-side template injection bypass"). Write "Not applicable — no CSP header served" ' +
-        'if none.',
-    ),
-  cookie_security: z
-    .string()
-    .min(1)
-    .describe(
-      'Session cookie security observations: HttpOnly, Secure, SameSite flags, and storage mechanism ' +
-        '(e.g. "Primary session cookie `sessionid` is missing HttpOnly; tokens are also stored in ' +
-        'localStorage, both accessible to JavaScript"). Drives exfiltration strategy.',
-    ),
-});
-
-const AuthStrategicIntelSchema = z.object({
-  authentication_method: z
-    .string()
-    .min(1)
-    .describe(
-      'How users authenticate: JWT, session cookie, OAuth, SAML, etc. Include any algorithm or library ' +
-        'details (e.g. "JWT (RS256) with hardcoded private key in lib/insecurity.ts:23").',
-    ),
-  session_token_details: z
-    .string()
-    .min(1)
-    .describe(
-      'Where tokens live and how they are protected: cookie name, storage mechanism (cookie vs ' +
-        'localStorage), cookie flags, expiration (e.g. "JWT stored in localStorage under key `token`; ' +
-        'cookie copy lacks HttpOnly/Secure/SameSite; 6-hour TTL with no revocation").',
-    ),
-  password_policy: z
-    .string()
-    .min(1)
-    .describe(
-      'Observed server-side password policy and storage: complexity rules, hashing algorithm, salt, ' +
-        '(e.g. "MD5 without salt via crypto.createHash; no server-side complexity policy; client-side ' +
-        '5-char minimum trivially bypassed").',
-    ),
-});
-
-const SsrfStrategicIntelSchema = z.object({
-  http_client_library: z
-    .string()
-    .min(1)
-    .describe(
-      'HTTP client library/libraries used for outbound requests (e.g. "axios 1.6", "node-fetch", ' +
-        '"requests", "HttpClient (Spring)"). Include version where it informs known bypass techniques.',
-    ),
-  request_architecture: z
-    .string()
-    .min(1)
-    .describe(
-      'How outbound requests are constructed and routed: proxy/middleware patterns, internal routing ' +
-        'rules (e.g. "Webhook URLs are POSTed directly without an outbound proxy; redirects are ' +
-        'followed by default with no maxRedirects limit").',
-    ),
-  internal_services: z
-    .string()
-    .min(1)
-    .describe(
-      'Internal endpoints, services, or cloud-metadata addresses discovered during analysis that an ' +
-        'SSRF could reach (e.g. "169.254.169.254 (AWS IMDS), internal admin API at admin.internal:8443, ' +
-        'PostgreSQL on localhost:5432").',
-    ),
-});
-
-const AuthzStrategicIntelSchema = z.object({
-  session_management_architecture: z
-    .string()
-    .min(1)
-    .describe(
-      'Session and authentication architecture relevant to authorization decisions: where user identity ' +
-        'comes from, whether the user ID is trusted by downstream guards (e.g. "JWT tokens in cookies; ' +
-        'user ID extracted from `req.user.id` and used directly in DB queries without ownership ' +
-        're-validation").',
-    ),
-  role_permission_model: z
-    .string()
-    .min(1)
-    .describe(
-      'Roles, capabilities, and where they live: identified roles, their privilege levels, and where ' +
-        'role/permission data is stored (e.g. "Three roles: user, moderator, admin. Role embedded in ' +
-        'JWT and database; checks inconsistent — many admin routes only check `req.user` presence").',
-    ),
-  resource_access_patterns: z
-    .string()
-    .min(1)
-    .describe(
-      'How resource IDs flow through the system and ownership patterns: e.g. "Most endpoints use path ' +
-        'parameters for resource IDs (/api/users/{id}); IDs are passed to DB queries without ownership ' +
-        'validation". Critical for IDOR exploitation.',
-    ),
-  workflow_implementation: z
-    .string()
-    .min(1)
-    .describe(
-      'Multi-step processes and state transitions: how workflow stages are tracked, whether prior-state ' +
-        'checks are enforced (e.g. "Multi-step processes use status fields in database; status ' +
-        'transitions do not verify prior state completion"). Drives context-based authz exploitation.',
-    ),
-});
-
-const STRATEGIC_INTEL_SCHEMAS: Record<VulnClass, z.ZodObject<ZodRawShape>> = {
-  injection: InjectionStrategicIntelSchema,
-  xss: XssStrategicIntelSchema,
-  auth: AuthStrategicIntelSchema,
-  ssrf: SsrfStrategicIntelSchema,
-  authz: AuthzStrategicIntelSchema,
-};
-
-// ============================================================================
-// EXPORTED TYPES
-// ============================================================================
-
-export type Pattern = z.infer<typeof PatternSchema>;
-export type FindingsSummaryInput = z.infer<typeof FindingsSummaryInputSchema>;
-export type SafeVectorInput = z.infer<typeof SafeVectorInputSchema>;
-export type SafeVectorsInput = z.infer<typeof SafeVectorsInputSchema>;
-export type BlindSpotItem = z.infer<typeof BlindSpotItemSchema>;
-export type BlindSpotsInput = z.infer<typeof BlindSpotsInputSchema>;
-
-export type InjectionStrategicIntel = z.infer<typeof InjectionStrategicIntelSchema>;
-export type XssStrategicIntel = z.infer<typeof XssStrategicIntelSchema>;
-export type AuthStrategicIntel = z.infer<typeof AuthStrategicIntelSchema>;
-export type SsrfStrategicIntel = z.infer<typeof SsrfStrategicIntelSchema>;
-export type AuthzStrategicIntel = z.infer<typeof AuthzStrategicIntelSchema>;
-
-// Discriminated by the agent class context — the renderer reads only the
-// sub-fields that apply to the active class.
-export type StrategicIntelligenceInput =
-  | InjectionStrategicIntel
-  | XssStrategicIntel
-  | AuthStrategicIntel
-  | SsrfStrategicIntel
-  | AuthzStrategicIntel;
-
-export interface VulnCollectorData {
-  readonly findings_summary?: FindingsSummaryInput;
-  readonly strategic_intelligence?: StrategicIntelligenceInput;
-  readonly safe_vectors?: SafeVectorsInput;
-  readonly blind_spots?: BlindSpotsInput;
-}
-
-export const VULN_TOOLS = [
-  'set_findings_summary',
-  'set_strategic_intelligence',
-  'set_safe_vectors',
-  'set_blind_spots',
-] as const;
-
-export type VulnToolName = (typeof VULN_TOOLS)[number];
-
-export type VulnToolStatus = 'called' | 'skipped';
-
-export type VulnCallStatus = Readonly<Record<VulnToolName, VulnToolStatus>>;
-
-// ============================================================================
-// RESPONSE HELPERS
-// ============================================================================
-
-interface ToolResult {
-  [x: string]: unknown;
-  content: Array<{ type: 'text'; text: string }>;
-  isError: boolean;
-}
-
-function createToolResult(response: { status: string; [key: string]: unknown }): ToolResult {
-  return {
-    content: [{ type: 'text', text: JSON.stringify(response, null, 2) }],
-    isError: response.status === 'error',
-  };
-}
-
-function successResult(data: Record<string, unknown>): ToolResult {
-  return createToolResult({ status: 'success', ...data });
-}
-
-function errorResult(message: string, errorType = 'ValidationError', retryable = true): ToolResult {
-  return createToolResult({ status: 'error', message, errorType, retryable });
-}
-
-// ============================================================================
-// SERVER FACTORY
-// ============================================================================
-
-export interface VulnCollectorServer {
-  server: McpSdkServerConfigWithInstance;
-  getAll(): VulnCollectorData;
-  getCallStatus(): VulnCallStatus;
-}
-
-export function createVulnCollector(vulnClass: VulnClass): VulnCollectorServer {
-  const state: {
-    findings_summary?: FindingsSummaryInput;
-    strategic_intelligence?: StrategicIntelligenceInput;
-    safe_vectors?: SafeVectorsInput;
-    blind_spots?: BlindSpotsInput;
-  } = {};
-
-  function alreadyCalled(toolName: VulnToolName): ToolResult {
-    return errorResult(
-      `${toolName} has already been called. Each tool may only be called once per run.`,
-      'DuplicateError',
-      false,
-    );
-  }
-
-  const setFindingsSummary = tool(
-    'set_findings_summary',
-    'Record the executive summary headline and the dominant vulnerability patterns observed across ' +
-      'your findings. Call exactly once before terminating. Becomes Section 1 (key outcome) and ' +
-      'Section 2 (patterns) of the rendered deliverable — this is the load-bearing emission for the ' +
-      'narrative .md and is required. Duplicate calls return "already called" and are no-ops. Empty ' +
-      'patterns array is acceptable (renders as "No dominant patterns identified") but key_outcome ' +
-      'is always required.',
-    FindingsSummaryInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.findings_summary) return alreadyCalled('set_findings_summary');
-      state.findings_summary = input;
-      return successResult({ set: 'set_findings_summary' });
-    },
-  );
-
-  const intelSchema = STRATEGIC_INTEL_SCHEMAS[vulnClass];
-  const setStrategicIntelligence = tool(
-    'set_strategic_intelligence',
-    `Record the environmental and defensive intelligence relevant to exploiting the ${vulnClass} ` +
-      'findings. Call exactly once before terminating. Becomes Section 3 of the rendered deliverable ' +
-      `and is the section the downstream exploit-${vulnClass} agent reads for strategic context. ` +
-      'Required. Duplicate calls return "already called" and are no-ops. Write "Not applicable" as ' +
-      'the field value when a sub-field does not apply to this run (rather than omitting).',
-    intelSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.strategic_intelligence) return alreadyCalled('set_strategic_intelligence');
-      state.strategic_intelligence = input as unknown as StrategicIntelligenceInput;
-      return successResult({ set: 'set_strategic_intelligence' });
-    },
-  );
-
-  const setSafeVectors = tool(
-    'set_safe_vectors',
-    'Record the input vectors, components, or endpoints that were analyzed and confirmed to have ' +
-      'robust, context-appropriate defenses. Call exactly once before terminating. Becomes Section 4 ' +
-      'of the rendered deliverable. Recommended (empty array is acceptable on runs where no vectors ' +
-      'were validated as safe, but explicit emission is preferred). The renderer sorts by ' +
-      '(subject, location) before rendering, so emission order does not affect output. Duplicate ' +
-      'calls return "already called" and are no-ops.',
-    SafeVectorsInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.safe_vectors) return alreadyCalled('set_safe_vectors');
-      state.safe_vectors = input;
-      return successResult({ set: 'set_safe_vectors', count: input.vectors.length });
-    },
-  );
-
-  const setBlindSpots = tool(
-    'set_blind_spots',
-    'Record analysis constraints, untraced code paths, or other coverage gaps. Call exactly once ' +
-      'before terminating. Becomes Section 5 of the rendered deliverable. Recommended (empty array ' +
-      'is acceptable on high-coverage runs, but explicit emission is preferred — readers expect ' +
-      'either documented gaps or an explicit "no gaps" signal). Duplicate calls return "already ' +
-      'called" and are no-ops.',
-    BlindSpotsInputSchema.shape,
-    async (input): Promise<ToolResult> => {
-      if (state.blind_spots) return alreadyCalled('set_blind_spots');
-      state.blind_spots = input;
-      return successResult({ set: 'set_blind_spots', count: input.items.length });
-    },
-  );
-
-  // set_blind_spots is withheld from classes without a Section 5 (auth, ssrf).
-  const tools = [
-    setFindingsSummary,
-    setStrategicIntelligence,
-    setSafeVectors,
-    ...(BLIND_SPOTS_CLASSES.has(vulnClass) ? [setBlindSpots] : []),
-  ];
-
-  const server: McpSdkServerConfigWithInstance = createSdkMcpServer({
-    name: 'vuln-collector',
-    version: '1.0.0',
-    tools,
-  });
-
-  function statusOf<K extends VulnToolName>(key: K): VulnToolStatus {
-    const flagMap: Record<VulnToolName, unknown> = {
-      set_findings_summary: state.findings_summary,
-      set_strategic_intelligence: state.strategic_intelligence,
-      set_safe_vectors: state.safe_vectors,
-      set_blind_spots: state.blind_spots,
-    };
-    return flagMap[key] ? 'called' : 'skipped';
-  }
-
-  return {
-    server,
-    getAll: (): VulnCollectorData => ({
-      ...(state.findings_summary && { findings_summary: state.findings_summary }),
-      ...(state.strategic_intelligence && { strategic_intelligence: state.strategic_intelligence }),
-      ...(state.safe_vectors && { safe_vectors: state.safe_vectors }),
-      ...(state.blind_spots && { blind_spots: state.blind_spots }),
-    }),
-    getCallStatus: (): VulnCallStatus => ({
-      set_findings_summary: statusOf('set_findings_summary'),
-      set_strategic_intelligence: statusOf('set_strategic_intelligence'),
-      set_safe_vectors: statusOf('set_safe_vectors'),
-      set_blind_spots: statusOf('set_blind_spots'),
-    }),
-  };
-}

apps/worker/src/paths.ts

@@ -9,6 +9,12 @@ 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');
+
 /** Default deliverables subdirectory relative to repoPath */
 export const DEFAULT_DELIVERABLES_SUBDIR = '.shannon/deliverables';
 
@@ -25,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/generate-totp.ts

@@ -9,8 +9,7 @@
 /**
  * generate-totp CLI
  *
- * Generates 6-digit TOTP codes for authentication.
- * Replaces the MCP generate_totp tool.
+ * Generates a TOTP code for the target's MFA.
  * Based on RFC 6238 (TOTP) and RFC 4226 (HOTP).
  *
  * Usage:
@@ -129,8 +128,12 @@ function main(): void {
     process.exit(1);
   }
 
+  // Strip base32 padding ('=') and whitespace so grouped/padded secrets
+  // (e.g. "JBSW Y3DP" or "...PXP=") pass validation instead of being rejected.
+  const normalizedSecret = secret.replace(/[=\s]/g, '');
+
   const base32Regex = /^[A-Z2-7]+$/i;
-  if (!base32Regex.test(secret)) {
+  if (!base32Regex.test(normalizedSecret)) {
     console.log(
       JSON.stringify({
         status: 'error',
@@ -142,7 +145,7 @@ function main(): void {
   }
 
   try {
-    const totpCode = generateTOTP(secret);
+    const totpCode = generateTOTP(normalizedSecret);
     const expiresIn = 30 - (Math.floor(Date.now() / 1000) % 30);
 
     console.log(

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

@@ -12,8 +12,7 @@
  * - Load prompt template using AGENTS[agentName].promptTemplate
  * - Create git checkpoint
  * - Start audit logging
- * - Invoke Claude SDK via runClaudePrompt
- * - Spending cap check using isSpendingCapBehavior
+ * - Invoke the pi agent via runPiPrompt
  * - Handle failure (rollback, audit)
  * - Validate output using AGENTS[agentName].deliverableFilename
  * - Render the deliverable to disk via the writeDeliverable hook (if provided)
@@ -23,8 +22,8 @@
  */
 
 import { fs, path } from 'zx';
-import { type ClaudePromptResult, runClaudePrompt, validateAgentOutput } from '../ai/claude-executor.js';
-import { getOutputFormat, getQueueFilename } from '../ai/queue-schemas.js';
+import { type PiPromptResult, runPiPrompt, validateAgentOutput } from '../ai/pi/pi-executor.js';
+import { createQueueSubmitTool, getQueueFilename } from '../ai/queue-schemas.js';
 import type { AuditSession } from '../audit/index.js';
 import { authStateFile } from '../audit/utils.js';
 import { AGENTS } from '../session-manager.js';
@@ -34,10 +33,10 @@ 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';
-import { commitGitSuccess, createGitCheckpoint, getGitCommitHash, rollbackGitWorkspace } from './git-manager.js';
+import { commitGitSuccess, createGitCheckpoint, rollbackGitWorkspace, withGitRepoLock } from './git-manager.js';
 import { loadPrompt } from './prompt-manager.js';
 
 /**
@@ -52,17 +51,17 @@ export interface AgentExecutionInput {
   configYAML?: string | undefined;
   pipelineTestingMode?: boolean | undefined;
   attemptNumber: number;
-  apiKey?: string | undefined;
   promptDir?: string | undefined;
-  providerConfig?: import('../types/config.js').ProviderConfig | undefined;
-  mcpServers?: Record<string, import('@anthropic-ai/claude-agent-sdk').McpServerConfig>;
+  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;
 }
 
 interface FailAgentOpts {
   attemptNumber: number;
-  result: ClaudePromptResult;
+  result: PiPromptResult;
   rollbackReason: string;
   errorMessage: string;
   errorCode: ErrorCode;
@@ -71,6 +70,43 @@ interface FailAgentOpts {
   context: Record<string, unknown>;
 }
 
+function errorCodeFromResult(result: PiPromptResult): ErrorCode {
+  if (result.errorType && Object.values(ErrorCode).includes(result.errorType as ErrorCode)) {
+    return result.errorType as ErrorCode;
+  }
+  return ErrorCode.AGENT_EXECUTION_FAILED;
+}
+
+function categoryForErrorCode(code: ErrorCode): PentestErrorType {
+  switch (code) {
+    case ErrorCode.GIT_CHECKPOINT_FAILED:
+    case ErrorCode.GIT_ROLLBACK_FAILED:
+      return 'filesystem';
+    case ErrorCode.PROMPT_LOAD_FAILED:
+      return 'prompt';
+    default:
+      return 'validation';
+  }
+}
+
+/** Wrap a failed git operation result into a PentestError attributed to the agent. */
+function gitFailureForAgent(
+  agentName: AgentName,
+  operation: string,
+  error: Error | undefined,
+  code: ErrorCode = ErrorCode.GIT_CHECKPOINT_FAILED,
+): PentestError {
+  const retryable = error instanceof PentestError ? error.retryable : true;
+  const message = error?.message ?? 'unknown git failure';
+  return new PentestError(
+    `Failed to ${operation} for ${agentName}: ${message}`,
+    'filesystem',
+    retryable,
+    { agentName, originalError: message },
+    code,
+  );
+}
+
 /**
  * Service for executing agents with full lifecycle management.
  *
@@ -109,12 +145,13 @@ export class AgentExecutionService {
       configYAML,
       pipelineTestingMode = false,
       attemptNumber,
-      apiKey,
       promptDir,
-      providerConfig,
-      mcpServers,
+      customTools,
+      failedClasses,
       writeDeliverable,
+      cancellationSignal,
     } = input;
+    const gitPaths = getAgentGitPaths(agentName);
 
     // 1. Load config (pre-parsed configData → raw YAML → file path)
     const configResult = await this.configLoader.loadOptional(configPath, configData, configYAML);
@@ -129,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,
@@ -148,9 +190,16 @@ export class AgentExecutionService {
       );
     }
 
-    // 3. Create git checkpoint before execution
+    // 3. Create git checkpoint before execution (scoped to this agent's paths)
     try {
-      await createGitCheckpoint(deliverablesPath, agentName, attemptNumber, logger);
+      const checkpointResult = await createGitCheckpoint(deliverablesPath, agentName, attemptNumber, logger, gitPaths);
+      if (!checkpointResult.success) {
+        const code =
+          checkpointResult.error instanceof PentestError && checkpointResult.error.code
+            ? checkpointResult.error.code
+            : ErrorCode.GIT_CHECKPOINT_FAILED;
+        return err(gitFailureForAgent(agentName, 'create git checkpoint', checkpointResult.error, code));
+      }
     } catch (error) {
       const errorMessage = error instanceof Error ? error.message : String(error);
       return err(
@@ -167,9 +216,10 @@ export class AgentExecutionService {
     // 4. Start audit logging
     await auditSession.startAgent(agentName, prompt, attemptNumber);
 
-    // 5. Execute agent
-    const outputFormat = getOutputFormat(agentName, distributedConfig?.exploit ?? true);
-    const result: ClaudePromptResult = await runClaudePrompt(
+    // 5. Execute agent. Vuln agents get a submit tool that captures the structured
+    //    exploitation queue (pi has no JSON-schema output format).
+    const submitTool = createQueueSubmitTool(agentName, distributedConfig?.exploit ?? true);
+    const result: PiPromptResult = await runPiPrompt(
       prompt,
       repoPath,
       '', // context
@@ -177,82 +227,106 @@ export class AgentExecutionService {
       agentName,
       auditSession,
       logger,
-      AGENTS[agentName].modelTier,
-      outputFormat,
-      apiKey,
+      customTools,
       path.relative(repoPath, deliverablesPath),
-      providerConfig,
-      mcpServers,
+      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, {
         attemptNumber,
         result,
         rollbackReason: 'execution failure',
         errorMessage: result.error || 'Agent execution failed',
-        errorCode: ErrorCode.AGENT_EXECUTION_FAILED,
-        category: 'validation',
+        errorCode,
+        category: categoryForErrorCode(errorCode),
         retryable: result.retryable ?? true,
         context: { agentName, originalError: result.error },
       });
     }
 
-    // 8. Write structured output to disk (vuln agents only)
-    const queueFilename = getQueueFilename(agentName);
-    if (result.structuredOutput !== undefined && queueFilename) {
-      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}`);
-    }
+    // 8-11. Write structured output, validate, render, and commit under one repo lock so
+    //       the write→validate→commit sequence is atomic against concurrent sibling agents.
+    let commitHash: string | undefined;
+    const finalizationError = await withGitRepoLock(async (): Promise<PentestError | null> => {
+      // 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} post-processing failed: ${errorMessage}`,
+          'validation',
+          true,
+          { agentName, originalError: errorMessage },
+          ErrorCode.OUTPUT_VALIDATION_FAILED,
+        );
+      }
+    });
+
+    if (finalizationError) {
+      const rollbackReason =
+        finalizationError.code === ErrorCode.OUTPUT_VALIDATION_FAILED
+          ? 'validation failure'
+          : 'post-processing failure';
       return this.failAgent(agentName, deliverablesPath, auditSession, logger, {
         attemptNumber,
         result,
-        rollbackReason: 'validation failure',
-        errorMessage: `Agent ${agentName} failed output validation`,
-        errorCode: ErrorCode.OUTPUT_VALIDATION_FAILED,
-        category: 'validation',
-        retryable: true,
-        context: { agentName, deliverableFilename: AGENTS[agentName].deliverableFilename },
+        rollbackReason,
+        errorMessage: finalizationError.message,
+        errorCode: finalizationError.code ?? ErrorCode.AGENT_EXECUTION_FAILED,
+        category: finalizationError.type,
+        retryable: finalizationError.retryable,
+        context: { agentName, ...finalizationError.context },
       });
     }
 
-    // 10. Render the deliverable to disk so the success commit below stages it
-    if (writeDeliverable) {
-      await writeDeliverable(deliverablesPath);
-    }
-
-    // 11. Success - commit deliverables, then capture checkpoint hash
-    await commitGitSuccess(deliverablesPath, agentName, logger);
-    const commitHash = await getGitCommitHash(deliverablesPath);
-
     const endResult: AgentEndResult = {
       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 }),
@@ -269,19 +343,41 @@ export class AgentExecutionService {
     logger: ActivityLogger,
     opts: FailAgentOpts,
   ): Promise<Result<AgentEndResult, PentestError>> {
-    await rollbackGitWorkspace(deliverablesPath, opts.rollbackReason, logger);
+    const rollbackResult = await rollbackGitWorkspace(
+      deliverablesPath,
+      opts.rollbackReason,
+      logger,
+      getAgentGitPaths(agentName),
+    );
 
     const endResult: AgentEndResult = {
       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,
     };
     await auditSession.endAgent(agentName, endResult);
 
-    return err(new PentestError(opts.errorMessage, opts.category, opts.retryable, opts.context, opts.errorCode));
+    const context = rollbackResult.success
+      ? opts.context
+      : {
+          ...opts.context,
+          rollbackFailed: true,
+          rollbackError: rollbackResult.error?.message ?? 'unknown rollback failure',
+          rollbackErrorCode:
+            rollbackResult.error instanceof PentestError
+              ? (rollbackResult.error.code ?? ErrorCode.GIT_ROLLBACK_FAILED)
+              : ErrorCode.GIT_ROLLBACK_FAILED,
+        };
+
+    return err(new PentestError(opts.errorMessage, opts.category, opts.retryable, context, opts.errorCode));
   }
 
   /**
@@ -313,11 +409,13 @@ export class AgentExecutionService {
   /**
    * Convert AgentEndResult to AgentMetrics for workflow state.
    */
-  static toMetrics(endResult: AgentEndResult, result: ClaudePromptResult): AgentMetrics {
+  static toMetrics(endResult: AgentEndResult, result: PiPromptResult): AgentMetrics {
     return {
       durationMs: endResult.duration_ms,
-      inputTokens: null, // Not currently exposed by SDK wrapper
-      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

@@ -0,0 +1,39 @@
+// 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.
+
+/**
+ * Per-agent git path scoping.
+ *
+ * Under parallel agent execution the deliverables git is shared, so each agent's
+ * checkpoint/commit/rollback must be limited to the files that agent actually
+ * writes. This resolves those paths from the agent's deliverable filename plus
+ * its structured exploitation queue (vuln agents only).
+ */
+
+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';
+
+/**
+ * Deliverable files an agent writes into the deliverables directory. Used to
+ * scope git operations so one agent never touches a sibling agent's output.
+ */
+export function getAgentGitPaths(agentName: AgentName): string[] {
+  const paths = [AGENTS[agentName].deliverableFilename];
+  const queueFilename = getQueueFilename(agentName);
+  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',
-  // Claude 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:
@@ -117,8 +79,10 @@ function classifyByErrorCode(code: ErrorCode, retryableFromError: boolean): { ty
     case ErrorCode.PROMPT_LOAD_FAILED:
       return { type: 'ConfigurationError', retryable: false };
 
-    // Git errors - non-retryable (indicates workspace corruption)
     case ErrorCode.GIT_CHECKPOINT_FAILED:
+      return { type: 'GitError', retryable: retryableFromError };
+
+    // Rollback errors leave the workspace state untrusted.
     case ErrorCode.GIT_ROLLBACK_FAILED:
       return { type: 'GitError', retryable: false };
 
@@ -141,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 };
   }
 }
@@ -159,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 (SDK, 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) ===
@@ -168,80 +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 };
-  }
-
-  // === 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 };
 }