restart-recovery

name	restart-recovery
description	Snapshot and restore full dev environment after machine restart. Captures running services, agency sessions, backlog state, and auto-recovers on login. Use when: about to restart, recovering from restart, setting up auto-recovery.
domain	workflow-recovery
confidence	high
source	manual
tools	[{"name":"powershell","description":"Execute recovery scripts and register Task Scheduler","when":"Always — scripts are OS-level"}]

Restart Recovery

When to Use

• You're about to restart/reboot the machine and want to preserve state
• The machine just rebooted and you need everything back
• You want auto-recovery on login (Task Scheduler / systemd / launchd)

When Not to Use

• Session was closed normally (use session-recovery plugin instead)
• Looking for git history (use git log)
• Only need to find a past session (use session-recovery plugin)

How It Works

Three phases: Snapshot → Recovery → Auto-trigger

Phase 1: Snapshot (Before Restart)

Create .squad/restart-snapshot.json capturing:

{
  "timestamp": "2026-03-17T18:00:00Z",
  "services": [
    { "name": "Squad Monitor", "status": "running" },
    { "name": "Ralph Watch", "status": "running" },
    { "name": "Dashboard UI", "status": "running" },
    { "name": "CLI Tunnel Hub", "status": "running" }
  ],
  "agency_sessions": [
    {
      "id": "128c9345-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "name": "RP/Aspire Research",
      "cwd": ".",
      "status": "running"
    }
  ],
  "ralph_status": {
    "rounds_completed": 3,
    "issues_processed": ["#778", "#800"],
    "rate_limited": true,
    "next_items": ["#763", "#795"]
  },
  "pending_git": {
    "uncommitted_changes": false,
    "unpushed_commits": 2
  }
}

How to create the snapshot:

1. Scan running processes for known services (Squad Monitor, Ralph Watch, Dashboard UI, CLI Tunnel Hub)
2. Query session_store for active agency sessions in the current working directory
3. Capture Ralph state (rounds, issues, rate limit status)
4. Check git status for uncommitted/unpushed work
5. Write to .squad/restart-snapshot.json

Phase 2: Recovery (After Restart)

Run scripts/recover-from-restart.ps1 (Windows) or scripts/recover-from-restart.sh (Linux/Mac).

The script:

1. Reads .squad/restart-snapshot.json
2. Validates all inputs (path traversal protection, UUID format checks)
3. Launches services via an allowlist (only known service names accepted)
4. Resumes agency sessions with validated session IDs
5. Prints a recovery summary

Manual recovery (in Copilot CLI):

recover from restart

Or:

agency copilot --yolo --agent squad -p "recover from restart - read .squad/restart-snapshot.json and restore everything"

Phase 3: Auto-trigger (Optional)

Windows (Task Scheduler):

$action = New-ScheduledTaskAction -Execute "pwsh.exe" -Argument "-NoProfile -ExecutionPolicy Bypass -File `"$PWD\scripts\recover-from-restart.ps1`""
$trigger = New-ScheduledTaskTrigger -AtLogOn
$settings = New-ScheduledTaskSettingsSet -AllowStartIfOnBatteries -DontStopIfGoingOnBatteries
Register-ScheduledTask -TaskName "Squad-RecoverFromRestart" -Action $action -Trigger $trigger -Settings $settings -Description "Auto-recover Squad services after restart"

Linux (systemd user service):

# ~/.config/systemd/user/squad-recover.service
[Unit]
Description=Squad Restart Recovery
After=network.target

[Service]
Type=oneshot
ExecStart=/bin/bash /path/to/repo/scripts/recover-from-restart.sh
WorkingDirectory=/path/to/repo

[Install]
WantedBy=default.target

Then: systemctl --user enable squad-recover.service

macOS (launchd):

<!-- ~/Library/LaunchAgents/com.squad.recover.plist -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.squad.recover</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>/path/to/repo/scripts/recover-from-restart.sh</string>
    </array>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

Then: launchctl load ~/Library/LaunchAgents/com.squad.recover.plist

Security

• Allowlist-only service launching — only known service names trigger pre-defined commands
• Path validation — all paths checked against repo root (no directory traversal)
• UUID format validation — session IDs must match strict UUID v4 pattern
• No shell injection — snapshot fields are never interpolated into shell commands

Scripts Reference

Script	Platform	Purpose
scripts/recover-from-restart.ps1	Windows	Full recovery with validation
scripts/recover-from-restart.sh	Linux/Mac	Full recovery with validation

Related

• session-recovery plugin — for finding and resuming individual past sessions
• This plugin handles full environment restore (multiple services + sessions + state)