Resume Workflow

Shannon’s workspace system allows you to resume interrupted or failed runs, picking up exactly where you left off without re-running completed agents.

How Workspaces Work

Every Shannon run creates a workspace — a directory in audit-logs/ that contains all execution state, deliverables, and progress tracking.

Run Creates Workspace

When you start Shannon, a workspace is created:

./shannon start URL=https://example.com REPO=repo-name

Output:

Workspace: example-com_shannon-1771007534808
Logs: ./shannon logs ID=example-com_shannon-1771007534808

Progress is Checkpointed

Each agent’s completion is saved as a git commit in the workspace, creating restore points.

Resume from Checkpoint

If Shannon stops (crash, timeout, manual stop), resume using the same workspace name:

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=example-com_shannon-1771007534808

Shannon detects completed agents and skips them, continuing from where it stopped.

Creating Named Workspaces

Use named workspaces for easier reference and resumability:

# Start with a custom name
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

# Resume later with the same name
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit

Workspace Names

Named: Easy to remember (e.g., q1-audit, prod-scan-2026)
Auto-generated: Unique but verbose (e.g., example-com_shannon-1771007534808)

Choose named workspaces for long-running audits or when you plan to resume frequently.

Resume Behavior

When resuming a workspace, Shannon:

Validates URL match - Ensures the URL matches the original run (prevents cross-target contamination)
Detects completed agents - Checks which agents have saved deliverables
Restores git checkpoint - Resets workspace to last successful agent commit
Skips completed agents - Jumps directly to the next incomplete agent
Continues execution - Runs remaining agents from the checkpoint

Example Resume Flow

Initial Run Interrupted

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

Progress:

✅ Pre-Recon (completed)
✅ Recon (completed)
✅ Vuln-Injection (completed)
❌ Vuln-XSS (interrupted)
⏸️ Remaining agents (not started)

Resume Command

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

Output:

Resuming workspace: my-audit
Completed agents: pre-recon, recon, vuln-injection
Starting from: vuln-xss

Execution Continues

Shannon skips completed agents and continues:

⏭️ Pre-Recon (skipped)
⏭️ Recon (skipped)
⏭️ Vuln-Injection (skipped)
▶️ Vuln-XSS (running)
⏸️ Remaining agents (pending)

Listing Workspaces

View all workspaces with their status and resumability:

./shannon workspaces

Output:

=== Shannon Workspaces ===

  WORKSPACE                      URL                            STATUS         DURATION   COST      
  ────────────────────────────────────────────────────────────────────────────────────────────────
  q1-audit                       https://example.com            in-progress    45m        $32.50    (resumable)
  example-com_shannon-17710...   https://example.com            failed         12m        $8.20     (resumable)
  prod-scan-2026                 https://prod.example.com       completed      1h 15m     $48.90    

3 workspaces found (2 resumable)

Resume with: ./shannon start URL=<url> REPO=<repo> WORKSPACE=<name>

Workspace Status

in-progress

Resumable

Run is active or was interrupted. Can be resumed.

failed

Resumable

Run encountered an error. Can be resumed to retry failed agent.

completed

Run finished successfully. Cannot be resumed (all agents completed).

Workspace Structure

Each workspace directory contains:

audit-logs/example-com_shannon-1771007534808/
├── session.json          # Workflow metadata, status, metrics
├── workflow.log          # Human-readable execution log
├── agents/               # Per-agent execution logs
│   ├── pre-recon.log
│   ├── recon.log
│   ├── vuln-injection.log
│   └── ...
├── prompts/              # Prompt snapshots for reproducibility
│   ├── pre-recon.txt
│   ├── recon.txt
│   └── ...
└── deliverables/
    └── comprehensive_security_assessment_report.md

Key Files

session.json

Tracks workflow state, completed agents, cost, and duration. Used by resume logic.

workflow.log

Human-readable log of all workflow events. Tail with ./shannon logs ID=<workspace>.

agents/

Individual agent logs with tool use, errors, and completion status.

deliverables/

Agent outputs copied from repo to workspace for self-contained audit trail.

Resume Validation

Shannon enforces strict validation when resuming:

URL Match Required

URL Mismatch RejectedThe URL parameter must match the original workspace URL. This prevents accidentally resuming a workspace from a different target.

# Original run
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit

# Resume with different URL (rejected)
./shannon start URL=https://other.com REPO=repo-name WORKSPACE=my-audit
# ERROR: URL mismatch. Workspace 'my-audit' was created for https://example.com

Deliverable Existence

Shannon verifies that completed agents have valid deliverables before marking them as skippable. If a deliverable is missing or corrupted, the agent re-runs.

Git Checkpoint Restore

Before resuming, Shannon:

Loads the last successful agent commit from workspace git history
Resets the workspace to that commit
Cleans up any incomplete deliverables from interrupted agents
Continues from a clean state

This ensures no partial or corrupted state from the interruption carries forward.

Use Cases

Crash Recovery

System crash or container restart during long-running pentestAction: Resume with same workspace name

Rate Limit Recovery

Hit API rate limits mid-runAction: Wait for limit reset, then resume

Manual Stop

Stop run intentionally to adjust configurationAction: Update config, resume with same workspace

Iterative Testing

Test agents incrementally during developmentAction: Run one phase, stop, review, resume

Examples

Resume After Crash

# Initial run crashes mid-execution
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit
# ... crashes during vuln-xss agent

# List workspaces to confirm
./shannon workspaces
# Shows: q1-audit | in-progress | 32m | $18.50 (resumable)

# Resume from checkpoint
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-audit
# Skips: pre-recon, recon, vuln-injection
# Continues from: vuln-xss

Resume After Rate Limit

# Hit rate limit during analysis phase
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=rate-limit-test
# ERROR: Rate limit exceeded (429)

# Wait for rate limit window to reset (5 hours for subscription plans)
# Check status
./shannon workspaces

# Resume after reset
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=rate-limit-test

Resume Auto-Named Workspace

# Start without explicit workspace name
./shannon start URL=https://example.com REPO=repo-name
# Workspace: example-com_shannon-1771007534808

# Stop manually
./shannon stop

# List workspaces to find auto-generated name
./shannon workspaces

# Resume with auto-generated name
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=example-com_shannon-1771007534808

Configuration Changes on Resume

Safe Changes
Unsafe Changes

These configuration changes are safe when resuming:

Pipeline settings - retry_preset, max_concurrent_pipelines
Environment variables - API keys, model overrides
Output directory - Change OUTPUT= path

# Resume with adjusted pipeline settings
./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit CONFIG=./configs/new-settings.yaml

These changes require a new workspace:

Authentication - Login credentials, TOTP secrets
Rules - Avoid/focus patterns
URL - Target URL (enforced by validation)

Changing authentication or rules mid-run may cause inconsistent results. Start a new workspace instead:

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=my-audit-v2 CONFIG=./configs/new-auth.yaml

Monitoring Resume Progress

Track resumed runs the same way as new runs:

Real-Time Logs
Temporal Web UI
View Logs

# Tail workflow log
./shannon logs ID=my-audit

# Output shows skip markers
[2026-03-03 10:15:23] Resuming workspace: my-audit
[2026-03-03 10:15:23] Skipping completed agent: pre-recon
[2026-03-03 10:15:23] Skipping completed agent: recon
[2026-03-03 10:15:23] Starting agent: vuln-xss

# View detailed workflow logs (requires workflow ID)
./shannon logs ID=my-audit_shannon-1771007534808

# Shows real-time progress and agent activity

Troubleshooting

URL mismatch error

Error:

ERROR: URL mismatch. Workspace 'my-audit' was created for https://example.com

Cause: Trying to resume with a different URL than the original run.Solution: Use the original URL or create a new workspace for the new URL.

Workspace not found

Error:

ERROR: Workspace 'my-audit' not found in ./audit-logs/

Cause: Workspace directory doesn’t exist or was deleted.Solution: Check workspace name with ./shannon workspaces or start a new run.

No agents to resume

Error:

ERROR: Workspace 'my-audit' has no incomplete agents

Cause: All agents completed successfully (status: completed).Solution: Workspace cannot be resumed. Start a new run if needed.

Resume starts from beginning

Issue: Resume doesn’t skip completed agents.Cause: Deliverables missing or corrupted in workspace.Solution: Check audit-logs/<workspace>/deliverables/ for expected files. If missing, agents re-run automatically.

Git checkpoint restore failed

Error:

ERROR: Failed to restore git checkpoint for workspace 'my-audit'

Cause: Workspace git history is corrupted or missing.Solution: Start a new workspace. Resume relies on git commits for checkpointing.

Best Practices

Use Named Workspaces

For long-running audits or when resumability is important:

./shannon start URL=https://example.com REPO=repo-name WORKSPACE=q1-production-audit

Monitor Progress

Keep ./shannon logs running in a separate terminal to catch failures early.

Preserve Workspaces

Avoid ./shannon stop CLEAN=true unless you want to delete all workspaces. Use ./shannon stop to preserve data.

Document Resume Points

Note which agent was running when interrupted to understand resume behavior.

Monitoring

Logs, Temporal UI, and workflow queries

Configuration

Adjust pipeline settings for rate limits

Get Started

Core Concepts

Guides

CLI Reference

Resume Workflow

How Workspaces Work

Creating Named Workspaces

Resume Behavior

Example Resume Flow

Listing Workspaces

Workspace Status

Workspace Structure

Key Files

Resume Validation

URL Match Required

Deliverable Existence

Git Checkpoint Restore

Use Cases

Crash Recovery

Rate Limit Recovery

Manual Stop

Iterative Testing

Examples

Resume After Crash

Resume After Rate Limit

Resume Auto-Named Workspace

Configuration Changes on Resume

Monitoring Resume Progress

Troubleshooting

Best Practices

Monitoring

Configuration

Build docs developers (and LLMs) love

Get Started

Core Concepts

Guides

CLI Reference

​How Workspaces Work

​Creating Named Workspaces

​Resume Behavior

​Example Resume Flow

​Listing Workspaces

​Workspace Status

​Workspace Structure

​Key Files

​Resume Validation

​URL Match Required

​Deliverable Existence

​Git Checkpoint Restore

​Use Cases

Crash Recovery

Rate Limit Recovery

Manual Stop

Iterative Testing

​Examples

​Resume After Crash

​Resume After Rate Limit

​Resume Auto-Named Workspace

​Configuration Changes on Resume

​Monitoring Resume Progress

​Troubleshooting

​Best Practices

​Related Resources

Monitoring

Configuration

Build docs developers (and LLMs) love

How Workspaces Work

Creating Named Workspaces

Resume Behavior

Example Resume Flow

Listing Workspaces

Workspace Status

Workspace Structure

Key Files

Resume Validation

URL Match Required

Deliverable Existence

Git Checkpoint Restore

Use Cases

Examples

Resume After Crash

Resume After Rate Limit

Resume Auto-Named Workspace

Configuration Changes on Resume

Monitoring Resume Progress

Troubleshooting

Best Practices

Related Resources