superkick 0.1.0

data/CLAUDE.md

@@ -0,0 +1,2226 @@
+# CLAUDE.md — Superkick
+
+This file exists so you don't have to rediscover Superkick's architecture every session. Read it before touching anything.
+
+## What Superkick is
+
+Superkick is a **Ruby gem** that transparently wraps AI coding CLIs (Claude Code, GitHub Copilot, OpenAI Codex, Google Gemini, Goose) in a PTY proxy and **injects external context** — GitHub CI results, PR reviews, PR comments — directly into the CLI at idle moments via a text prompt.
+
+It has two runtime processes:
+- **`superkick agent`** — the PTY proxy process, one per AI CLI agent
+- **`superkick server`** — the background server that runs monitors and orchestrates injection
+
+They communicate over a Unix socket (`~/.superkick/run/server.sock`) using a simple JSON control protocol.
+
+## Architecture at a glance
+
+```
+superkick agent (agent process)
+┌──────────────────────────────────────┐
+│ PtyProxy                             │         superkick server process
+│  │                                   │ Control ┌───────────────────────────────────┐
+│  ├─owns─► Buffer::Server             │◄───────►│ Control::Server (server.sock)     │
+│  │         (buffer-<id>.sock)        │         │                                   │
+│  ├─owns─► [Hosted::Buffer::Bridge]  │         │ AgentStore                        │
+│  │         (hosted mode only)        │         │  └─ Agent                         │
+│  ├─owns─► [Hosted::Attach::Bridge]  │         │      ├─ monitors: { … }           │
+│  │         (hosted mode only)        │         │      ├─ buffer_socket_path ◄──────┼─┐
+│  ├─owns─► OutputLogger               │         │      └─ output_log_path           │ │
+│  ├─owns─► SessionRecorder           │         │      └─ recording_path            │ │
+│  │         (logs/<id>.log)           │         │           (transient links)       │ │
+│  └─owns─► InputBuffer                │         │                                   │ │
+│            (partial input + guards)  │         │ Buffer::Client ──────────────────►│ │
+│                                      │         │  ├─ (default: Unix socket) ───────┼─┘
+│  proxy_stdin  ──► InputBuffer ──►PTY │         │  └─ Hosted::Buffer::Client ──────►│
+│  proxy_output ──► guard detect ──►out│         │       └─► Hosted::Buffer::RelayStore│
+│               └──► OutputLogger      │         │            └─► Hosted::Buffer::Relay┼─┐
+│  drain_inject ──────────────────►PTY │         │                    ▲ WebSocket     │ │
+└──────────────────────────────────────┘         │                                   │ │
+          │ PTY                                  │ Hosted::Attach::RelayStore        │ │
+          ▼                                      │  └─► Hosted::Attach::Relay ──────►│ │
+┌──────────────────────────────────────┐         │       (RW exclusivity, history)   │ │
+│ AI CLI (claude / copilot / …)        │─MCP─►   │                                   │ │
+└──────────────────────────────────────┘    │    │ Supervisor                        │ │
+                                            │    │  └─ owns monitor threads          │ │
+   Hosted::Bridge subclasses ── WebSocket ──┼────┼───────────────────────────────────┼─┘
+   (Buffer + Attach, in agent process)      │    │ Injector (uses Buffer::Client)    │
+                                            │    │                                   │
+                                            └───►│ McpServer (local mode)            │
+                                                 └───────────────────────────────────┘
+
+In hosted mode, MCP flows through a transparent stdio proxy:
+```
+AI CLI → stdio → Hosted::McpProxy → POST /api/v1/mcp → Hosted Server
+```
+```
+
+The agent registration sequence (multi-step with environment probing):
+1. `PtyProxy` sends `register` to the server (no monitors — just agent metadata and `working_dir`)
+2. Server responds with `environment_request` containing an array of action hashes (collected from all registered monitor probes via `Monitor.all_environment_actions`)
+3. `PtyProxy` executes the actions via `EnvironmentExecutor` in the agent's working directory
+4. `PtyProxy` sends `register_environment` with the environment snapshot
+5. Server runs probes server-side using the snapshot, merges with YAML-configured monitors, and starts monitor threads
+
+The injection sequence when a monitor emits an event:
+1. `Monitor#dispatch` calls `Injector#inject`
+2. `TemplateRenderer` renders the Liquid template for the event type
+3. Injector sends `enqueue_injection` to the agent's `Buffer::Server` via `Buffer::Client` (fire-and-forget)
+4. Agent's `InjectionQueue` checks preconditions locally (idle state, guards)
+5. `InjectionQueue` writes: **C-c → blank Enter → rendered prompt + Enter → restore partial input**
+6. `InjectionQueue` reports result back to server via `injection_result` IPC
+7. `NotificationDispatcher` fires both global notifiers and per-agent notifiers (injected via `_spawn_notifiers`) in a background thread to alert the user. Stateful notifiers (e.g. Slack in API mode) can correlate events for the same agent (thread replies, email threading, etc.).
+
+## Directory structure
+
+```
+superkick/
+├── exe/superkick                   # CLI entry point (requires lib/superkick/cli)
+├── lib/
+│   └── superkick/
+│       ├── cli.rb               # Thor CLI — registers subcommands (server, agent, monitor, spawner, mcp, team, goal, notifier, repository, setup, approve, reject, approvals)
+│       ├── cli/
+│       │   ├── server.rb        # superkick server: start, stop, status, log
+│       │   ├── setup.rb         # superkick setup: start (interactive first-time setup wizard)
+│       │   ├── agent.rb         # superkick agent: start, list, log, stop, attach, claim, unclaim, cost, report-cost, add-monitor, remove-monitor, add-notifier, remove-notifier
+│       │   ├── monitor.rb       # superkick monitor: list, install-templates
+│       │   ├── spawner.rb       # superkick spawner: list, start, stop, install-templates
+│       │   ├── team.rb          # superkick team: list, status, watch, stop, artifacts, artifact, message, spawn-worker
+│       │   ├── mcp.rb           # superkick mcp: start, configure
+│       │   ├── goal.rb          # superkick goal: list, signal
+│       │   ├── notifier.rb      # superkick notifier: list
+│       │   ├── repository.rb    # superkick repository: list
+│       │   └── completion.rb    # superkick completion: install, hidden helpers for dynamic shell completions
+│       ├── server.rb            # Server lifecycle (startup, signal handling, shutdown)
+│       ├── mcp_server.rb        # MCP stdio server exposing tools to the AI CLI
+│       ├── registry.rb          # Superkick::Registry — shared test isolation for class-level registries
+│       ├── configuration.rb     # Superkick::Configuration — all tuneable settings
+│       ├── yaml_config.rb       # YAML+ERB config loader
+│       ├── pty_proxy.rb         # 3-thread PTY wrapper (stdin / output / inject queue)
+│       ├── environment_executor.rb # Agent-side action executor for server-driven probes
+│       ├── input_buffer.rb      # Tracks partial keystrokes + injection guard state
+│       ├── connection.rb        # Connection — newline-delimited JSON framing (shared by control + data plane)
+│       ├── client_registry.rb   # ClientRegistry — shared module for client factory methods (used by Control, Buffer, Attach)
+│       ├── buffer/
+│       │   ├── server.rb       # Buffer::Server — per-agent Unix socket (get/guards_active/inject/idle_state)
+│       │   └── client.rb       # Buffer::Client — Unix socket implementation + .from factory
+│       ├── hosted/
+│       │   ├── bridge.rb       # Hosted::Bridge — abstract base class for agent-side WebSocket bridges (raw WebSocket, not ActionCable)
+│       │   ├── mcp_proxy.rb    # Hosted::McpProxy — transparent stdio-to-HTTP MCP proxy for hosted mode
+│       │   ├── buffer/
+│       │   │   ├── client.rb   # Hosted::Buffer::Client — routes commands through WebSocket relays
+│       │   │   ├── bridge.rb   # Hosted::Buffer::Bridge — agent-side bridge to hosted server (subclass of Hosted::Bridge)
+│       │   │   ├── relay.rb    # Hosted::Buffer::Relay — server-side per-agent WebSocket relay
+│       │   │   └── relay_store.rb # Hosted::Buffer::RelayStore — thread-safe relay registry
+│       │   ├── control/
+│       │   │   └── client.rb   # Hosted::Control::Client — HTTPS control client for remote servers
+│       │   └── attach/
+│       │       ├── client.rb   # Hosted::Attach::Client — WebSocket attach subclass
+│       │       ├── bridge.rb   # Hosted::Attach::Bridge — agent-side attach bridge (subclass of Hosted::Bridge)
+│       │       ├── relay.rb    # Hosted::Attach::Relay — server-side attach relay/mux (RW exclusivity, history, idle timeout)
+│       │       └── relay_store.rb # Hosted::Attach::RelayStore — thread-safe attach relay registry
+│       ├── attach/
+│       │   ├── protocol.rb      # Attach::Protocol — binary frame protocol (OUTPUT, INPUT, META, RESIZE, HISTORY, ERROR, HELLO, COMMAND, NOTIFY)
+│       │   ├── server.rb        # Attach::Server — per-agent attach endpoint with RW exclusivity, force-takeover, idle timeout, broadcast callbacks
+│       │   └── client.rb        # Attach::Client — Unix socket implementation + .from factory, session logic
+│       ├── history_buffer.rb    # Ring buffer for PTY output replay on attach connect
+│       ├── output_logger.rb     # Tees PTY output to per-agent log files with rotation
+│       ├── session_recorder.rb  # Records timestamped sessions in asciicast v2 (input + output + resize)
+│       ├── setup.rb             # Setup — interactive config.yml generator with integration discovery
+│       ├── injection_guard.rb   # Named guards that block injection (cleared on submit)
+│       ├── injection_queue.rb   # Agent-side injection queue with TTL, priority, supersede-by-key
+│       ├── process_runner.rb    # Unified subprocess execution with reliable timeouts
+│       ├── injector.rb          # Orchestrates a single injection attempt
+│       ├── template_renderer.rb # Liquid rendering with template filters + notification template resolution
+│       ├── template_filters.rb  # Core Liquid filters (time, short_sha, truncate)
+│       ├── notifier.rb          # Abstract Notifier base class + registry + lifecycle events
+│       ├── notifier_state_store.rb # NotifierStateStore — injectable key-value state for stateful notifiers
+│       ├── notification_dispatcher.rb # Stateful notification dispatcher — long-lived notifier instances
+│       ├── drop.rb              # Superkick::Drop — base class for Liquid Drops with serialize/rehydrate
+│       ├── drops.rb             # Core Drops: TeamDrop, SpawnerDrop, MonitorDrop, AgentDrop
+│       ├── notifiers/
+│       │   ├── terminal_bell.rb # Writes BEL (\a) to stderr — zero-config default
+│       │   └── command.rb       # Runs a shell command with SUPERKICK_* env vars
+│       ├── poller.rb            # Abstract Poller base class — shared run loop for monitors & spawners
+│       ├── monitor.rb           # Abstract Monitor base class (extends Poller) + Monitor::Probe + registries
+│       ├── spawner.rb           # Abstract Spawner base class (extends Poller) — server-level agent spawners
+│       ├── repository_source.rb # Repository, RepositorySource base + CompositeRepositorySource
+│       ├── local/
+│       │   └── repository_source.rb # Local::RepositorySource — single-repo or directory-scan source
+│       ├── agent.rb             # Live agent object (id, monitors, notifiers, buffer_socket_path, cost, team, role, goal_summary, working_dir, environment)
+│       ├── agent/
+│       │   ├── runtime.rb      # Agent::Runtime — abstract base class + registry for agent process runtimes
+│       │   ├── runtimes.rb     # Requires all built-in runtimes
+│       │   └── runtimes/
+│       │       └── local.rb    # Agent::Runtime::Local — spawns agent processes via Process.spawn (default)
+│       ├── agent_store.rb       # Thread-safe agent registry with JSON persistence + dedup
+│       ├── team/
+│       │   ├── log.rb          # Team::Log — append-only ndjson team communication log
+│       │   ├── log_store.rb    # Team::LogStore — server-level lazy registry of Team::Log instances
+│       │   ├── artifact_store.rb # Team::ArtifactStore — per-team persistent artifact storage
+│       │   ├── log_entry_drop.rb # Liquid Drop for Team::Log entries in team digest templates
+│       │   ├── log_monitor.rb # Team::LogMonitor — polls team log, injects digest events
+│       │   └── log_notifier.rb # Team::LogNotifier — internal notifier that writes team log entries
+│       ├── spawn/
+│       │   ├── agent_spawner.rb # Spawn::AgentSpawner — manages repository acquisition and agent subprocess lifecycle
+│       │   ├── handler.rb      # Spawn::Handler — event handler for spawners (dedup, approval gates)
+│       │   ├── injector.rb     # Spawn::Injector — kickoff prompt injection into newly spawned agents
+│       │   ├── approval_store.rb # Spawn::ApprovalStore — pending approval + rejection tracking for spawn gates
+│       │   ├── workflow_validator.rb # Spawn::WorkflowValidator — static cycle detection for spawner workflows
+│       │   └── workflow_executor.rb # Spawn::WorkflowExecutor — resolves workflow config, enriches events, transfers VCS state
+│       ├── supervisor.rb       # Supervisor — starts/stops monitor + spawner threads
+│       ├── control/
+│       │   ├── client.rb        # Control::Client — Unix socket implementation + .from factory
+│       │   ├── server.rb        # Control::Server — Unix socket control server
+│       │   └── reply.rb         # Control::Reply — typed response wrapper
+│       ├── goal.rb              # Superkick::Goal base class + registry — spawned agent goal checks
+│       ├── goals/
+│       │   ├── agent_exit.rb    # Completes when the AI CLI process exits
+│       │   ├── command.rb       # Runs a shell command periodically; success on exit 0
+│       │   └── agent_signal.rb  # Completes when AI CLI calls superkick_signal_goal MCP tool (default goal type)
+│       ├── version_control.rb   # Superkick::VersionControl base class + registry + VersionControl::Probe base
+│       ├── cost_accumulator.rb   # Thread-safe per-agent cost tracking
+│       ├── cost_extractor.rb    # Line-buffered PTY output cost parsing
+│       ├── cost_poller.rb       # Periodic cost command injection for stale agents
+│       ├── budget_checker.rb    # Multi-level budget evaluation (agent/spawner/global)
+│       ├── driver.rb            # Superkick::Driver base class + registry + CostPattern + normalize/merge helpers
+│       ├── driver/
+│       │   └── profile_source.rb # Driver::ProfileSource base + StaticProfileSource — named driver configs
+│       ├── drivers.rb           # Requires driver.rb + all built-in drivers
+│       ├── drivers/
+│       │   ├── claude_code.rb
+│       │   ├── copilot.rb
+│       │   ├── codex.rb
+│       │   ├── gemini.rb
+│       │   └── goose.rb
+│       ├── templates/
+│       │   ├── workflow/         # Default Liquid templates for workflow spawner events
+│       │   └── team_log/         # Default Liquid templates for team agent events
+│       └── integrations/
+│           ├── docker/
+│           │   ├── runtime.rb  # Integrations::Docker::Runtime — provisions agents in Docker containers
+│           │   ├── client.rb   # Integrations::Docker::Client — Faraday-based Docker Engine API client
+│           │   └── test/       # Docker runtime + client tests
+│           ├── git/
+│           │   ├── version_control.rb # Integrations::Git::VersionControl — worktree/clone adapter + Git::Probe
+│           │   ├── repository_source.rb # Integrations::Git::RepositorySource — single-repo source for URL-based git repos
+│           │   └── test/        # Git version control + repository source tests
+│           ├── github/
+│           │   ├── monitor.rb   # Polls CI checks, PR comments, PR reviews via Octokit
+│           │   ├── probe.rb     # Auto-detects repo/branch from git remote
+│           │   ├── goal.rb      # Integrations::GitHub::PrMergedGoal — completes when a PR is merged
+│           │   ├── issue_goal.rb # Integrations::GitHub::IssueResolvedGoal — completes when an issue is closed
+│           │   ├── issue_spawner.rb # Spawns agents for new/reopened GitHub issues
+│           │   ├── check_failed_spawner.rb # Spawns agents when GitHub checks fail on watched branches
+│           │   ├── repository_source.rb # Integrations::GitHub::OrganizationRepositorySource — fetches repositories from a GitHub organization
+│           │   ├── drops.rb      # Liquid Drops (IssueDrop, PullRequestDrop, CommentDrop, ReviewDrop, CommitDrop, CheckRunDrop) for type-safe template access
+│           │   ├── templates/   # Liquid templates for GitHub events + spawn templates
+│           │   └── test/        # GitHub monitor, spawners, goals, drops tests
+│           ├── circleci/
+│           │   ├── monitor.rb   # Polls CircleCI pipelines/workflows via Faraday
+│           │   ├── probe.rb     # Auto-detects from .circleci/config.yml + git remote
+│           │   ├── templates/   # Liquid templates for CircleCI events
+│           │   └── test/        # CircleCI monitor + probe tests
+│           ├── shortcut/
+│           │   ├── monitor.rb   # Polls Shortcut stories + related stories via Faraday
+│           │   ├── probe.rb     # Auto-detects story ID from sc-XXXXX branch pattern
+│           │   ├── spawner.rb   # Polls Shortcut search for new stories to spawn agents
+│           │   ├── drops.rb      # Liquid Drops (MemberDrop, TaskDrop, CommentDrop) for type-safe template access
+│           │   ├── templates/   # Liquid templates for Shortcut events + spawn templates
+│           │   └── test/        # Shortcut monitor, probe, spawner tests
+│           ├── bugsnag/
+│           │   ├── spawner.rb   # Polls Bugsnag errors API for open errors to spawn agents
+│           │   ├── templates/   # Liquid templates for Bugsnag spawn events
+│           │   └── test/        # Bugsnag spawner tests
+│           ├── shell/
+│           │   ├── monitor.rb   # Runs a shell command each tick, dispatches on exit status
+│           │   ├── templates/   # Liquid templates for shell events
+│           │   └── test/        # Shell monitor tests
+│           ├── slack/
+│           │   ├── drops.rb     # Liquid Drops (MessageDrop, UserDrop, ChannelDrop) for Slack events
+│           │   ├── notifier.rb  # Posts Block Kit messages to Slack (webhook or API)
+│           │   ├── spawner.rb   # Polls Slack channel for new messages to spawn agents
+│           │   ├── thread_monitor.rb # Polls Slack thread for replies, injects as high-priority events
+│           │   ├── templates/   # Liquid templates for Slack spawn + thread events
+│           │   └── test/        # Slack notifier, spawner, thread monitor, drops tests
+│           ├── datadog/
+│           │   ├── notifier.rb  # Sends events + metrics to Datadog via DogStatsD (UDP)
+│           │   ├── spawner.rb   # Polls Datadog Error Tracking API for open errors to spawn agents
+│           │   ├── alert_spawner.rb # Polls Datadog Monitors API for triggered alerts to spawn agents
+│           │   ├── alert_monitor.rb # Polls a specific Datadog monitor for status changes
+│           │   ├── alert_goal.rb # Goal that completes when a Datadog monitor recovers to OK
+│           │   ├── templates/   # Liquid templates for Datadog spawn + monitor events
+│           │   └── test/        # Datadog notifier, spawner, alert spawner, alert monitor, alert goal tests
+│           └── honeybadger/
+│               ├── notifier.rb  # Sends structured events to Honeybadger Insights (HTTP)
+│               ├── spawner.rb   # Polls Honeybadger Faults API for unresolved faults to spawn agents
+│               ├── templates/   # Liquid templates for Honeybadger spawn events
+│               └── test/        # Honeybadger notifier + spawner tests
+├── test/
+│   ├── test_helper.rb           # Minitest setup, TEST_HOME tmpdir, silenced logger
+│   ├── buffer/
+│   │   └── client_test.rb       # Buffer::Client transport selection + Unix socket tests
+│   ├── hosted/
+│   │   ├── bridge_test.rb       # Hosted::Bridge base class tests
+│   │   ├── mcp_proxy_test.rb   # Hosted::McpProxy stdio-to-HTTP proxy tests
+│   │   ├── buffer/
+│   │   │   ├── client_test.rb   # Hosted::Buffer::Client relay routing tests
+│   │   │   ├── relay_test.rb    # Hosted::Buffer::Relay WebSocket relay tests
+│   │   │   └── relay_store_test.rb # Hosted::Buffer::RelayStore registry tests
+│   │   ├── attach/
+│   │   │   ├── relay_test.rb    # Hosted::Attach::Relay relay/mux tests
+│   │   │   └── relay_store_test.rb # Hosted::Attach::RelayStore registry tests
+│   │   └── control/
+│   │       └── client_test.rb   # Hosted::Control::Client HTTPS tests
+│   ├── control/
+│   │   └── client_test.rb       # Control::Client transport selection + Unix socket tests
+│   ├── agent/
+│   │   └── runtimes/
+│   │       └── local_test.rb        # Agent::Runtime::Local tests
+│   ├── integration/                 # Cross-component integration tests
+│   │   ├── test_helper.rb           # Integration test helper (RecordingRuntime, Thor parser, etc.)
+│   │   ├── spawn_pipeline_test.rb   # Spawn command construction ↔ CLI parsing ↔ PtyProxy kwargs
+│   │   ├── server_agent_lifecycle_test.rb # Server ↔ agent IPC lifecycle (register, unregister, monitors)
+│   │   ├── injection_flow_test.rb   # Injector → Buffer::Client → Buffer::Server → InjectionQueue
+│   │   └── harness/                 # Test harness scripts for subprocess tests
+│   │       └── fake_agent.rb        # Dual-mode: records ARGV/env (basic) or full IPC lifecycle (with signal file)
+│   ├── environment_executor_test.rb # EnvironmentExecutor tests
+│   ├── setup_test.rb               # Setup core logic tests
+│   ├── setup_config_test.rb        # Setup config generation tests
+│   └── *_test.rb                # One file per core lib class
+├── docs/
+│   ├── README.md                   # Documentation index (Diataxis framework)
+│   ├── tutorials/                  # Step-by-step learning guides
+│   │   ├── getting-started.md      # First injection experience
+│   │   ├── first-spawner-pipeline.md # Issue-to-PR automation
+│   │   └── team-workflow.md        # Multi-repo agent teams
+│   ├── how-to/                     # Task-oriented recipes
+│   │   ├── customize-templates.md  # Template override system
+│   │   ├── configure-notifications.md # Notification recipes
+│   │   └── troubleshooting.md      # Diagnosing common issues
+│   ├── explanation/                # Conceptual discussions
+│   │   ├── injection-model.md      # How the PTY proxy and injection work
+│   │   ├── spawner-workflows.md    # Workflow design, composition, VCS inheritance
+│   │   └── agent-teams.md          # Team coordination model
+│   ├── reference/                  # Lookup information
+│   │   ├── templates.md            # Template variables per event type
+│   │   └── event-types.md          # All event types and payloads
+│   └── planning/                   # Internal planning docs (not published)
+├── skills/
+│   ├── superkick-new-driver/       # Step-by-step guide for adding a new AI CLI driver
+│   ├── superkick-new-goal/         # Step-by-step guide for adding a new goal type
+│   ├── superkick-new-monitor/      # Step-by-step guide for adding a new monitor
+│   ├── superkick-new-notifier/     # Step-by-step guide for adding a new notifier
+│   ├── superkick-new-spawner/      # Step-by-step guide for adding a new spawner
+│   └── superkick-update-docs/     # Guide for updating documentation after implementation changes
+├── .github/workflows/ci.yml     # GitHub Actions: test matrix + lint
+├── Rakefile                     # rake test, rake standard, rake standard:fix
+└── superkick.gemspec
+```
+
+## Key classes
+
+### `Superkick::EnvironmentExecutor` (`environment_executor.rb`)
+Agent-side action executor for server-driven probes. The server sends an array of action hashes describing what environment data it needs, and the executor runs each action in the agent's working directory.
+
+Supported actions:
+- `:git_branch` → current git branch name (String or nil)
+- `:git_remotes` → parsed git remotes (Array of `{name:, url:}` or nil)
+- `:file_exists` → file existence checks (Hash of `{path => Boolean}`)
+
+Constructor: `initialize(working_dir:)`.
+Key method: `execute(actions)` → merged results Hash keyed by action name.
+
+### `Superkick::PtyProxy` (`pty_proxy.rb`)
+Wraps the AI CLI in a PTY. Three threads:
+- `proxy_stdin` — reads raw keystrokes from `$stdin`, feeds `InputBuffer`, forwards to pty master
+- `proxy_output` — reads CLI output, writes to `$stdout`, tees to `OutputLogger` and `SessionRecorder`, updates `@last_output_at` and `@at_prompt`, calls `update_guards`, feeds `CostExtractor` for cost data extraction
+- `drain_inject_queue` — blocks on `@inject_queue.pop`, writes bytes to pty master
+
+On startup it creates a `Buffer::Server`, an `OutputLogger`, and (when `session_recording_enabled`) a `SessionRecorder`. Registration is multi-step: first sends `register` to the server (agent metadata and `working_dir: Dir.pwd`, no monitors), receives an `environment_request` containing action hashes, executes them via `EnvironmentExecutor`, then sends `register_environment` with the results so the server can run probes and start monitors. When `server_type` is `:hosted`, it also starts a `Hosted::Buffer::Bridge` and a `Hosted::Attach::Bridge` that maintain persistent WebSocket connections to the hosted server, bridging remote buffer commands and attach sessions respectively. In hosted mode, the `SessionRecorder` is wired with a `Store::Http` that uploads the completed recording on close. Accepts optional `agent_id:`, `headless:`, `team_id:`, `role:`, and `team_log:` parameters. The `agent_id:` and `headless:` flags are set by `Spawn::AgentSpawner` via hidden CLI options. On exit it closes the recorder and logger and unregisters.
+
+When spawning the AI CLI process, PtyProxy sets `SUPERKICK_AGENT_ID` in the child process environment so the MCP server subprocess can identify the agent without requiring the AI to pass its own ID.
+
+Cost extraction: the `proxy_output` thread feeds ANSI-stripped output text to a lazily-initialized `CostExtractor` (only if the driver has `cost_patterns`). Extracted cost deltas are reported to the server via `report_cost` IPC requests (best-effort, failures are silently logged).
+
+### `Superkick::OutputLogger` (`output_logger.rb`)
+Manages writing PTY output to a per-agent log file at `~/.superkick/logs/<agent-id>.log`. Raw bytes (including ANSI escape codes) are written in append mode with sync flushing so `tail -f` works in real time. Simple size-based rotation: one rotated file (`*.1`). When the log exceeds `MAX_SIZE` (10 MB), the current file becomes `.1` and a new file starts.
+
+### `Superkick::SessionRecorder` (`session_recorder.rb`)
+Records complete, timestamped agent sessions (input + output) in the asciicast v2 format at `~/.superkick/recordings/<agent-id>.cast`. Thread-safe via Mutex (three PtyProxy threads write concurrently). Uses monotonic clock for elapsed time computation. Simple size-based rotation (same pattern as `OutputLogger`, `.1` suffix). On `close`, calls `@store.upload` if a store is present (hosted mode). Lifecycle follows `OutputLogger`: create → start → record_* → close.
+
+Inner classes:
+- `SessionRecorder::Store` — abstract upload interface for completed recordings
+- `SessionRecorder::Store::Noop` — local mode, recordings stay on disk
+- `SessionRecorder::Store::Http` — hosted mode, uploads `.cast` file to hosted server via `POST /api/v1/agents/{agent_id}/recording`. Best-effort — failures are logged as warnings
+
+### `Superkick::Buffer::Server` (`buffer/server.rb`)
+Per-agent Unix socket server running inside the `superkick agent` process. Server-side components send buffer commands here (in local mode directly, in hosted mode via `Hosted::Buffer::Relay` → `Hosted::Buffer::Bridge`). Accepts six commands:
+- `get` — returns current partial input from `InputBuffer`
+- `guards_active` — returns whether any injection guards are active
+- `inject` — enqueues base64-encoded bytes into `PtyProxy#inject_queue`
+- `idle_state` — returns `{ seconds_idle:, at_prompt: }` from `PtyProxy`
+- `enqueue_injection` — enqueues a rendered prompt into the agent-side `InjectionQueue` with priority, TTL, and supersede key
+- `ping` — health check, returns `{ ok: true }`
+
+### `Superkick::Buffer::Client` (`buffer/client.rb`)
+Default Unix socket implementation of the buffer client. All server-side components (`Injector`, `Spawn::Injector`, `CostPoller`, `Supervisor`, `Control::Server`) use this class via the `buffer_client:` constructor parameter.
+
+The `Buffer` module extends `ClientRegistry` and provides `Buffer.client_from(store:, config:, relay_store:)` — returns a `Buffer::Client` (Unix socket) for `:local` server type, or the registered hosted client for `:hosted`. Hosted subclasses register via `Buffer.register_client(:hosted, klass)`. The `relay_store:` is only needed in hosted mode.
+
+Each client class defines a `from` class method that knows how to construct itself from config kwargs.
+
+The base class is the Unix socket implementation. Each request opens a fresh `UNIXSocket`, sends one JSON message via `Connection`, reads one response, and closes. Resolves the socket path from the `AgentStore`.
+
+Constructor: `initialize(store:)`.
+
+Defines a shared exception class:
+- `Buffer::Client::AgentUnreachable` — raised when the agent's buffer endpoint is unreachable.
+
+Key methods:
+- `send_command(agent_id, command, **params)` — fire-and-forget (logs and swallows `AgentUnreachable`)
+- `probe(agent_id)` — ping the agent to verify it's alive
+- `request(agent_id, command, **params)` — send a command and return the parsed response
+- `reachable?(agent_id)` — check if the agent is reachable via the buffer channel
+
+### `Superkick::Hosted::Buffer::Client` (`hosted/buffer/client.rb`)
+WebSocket relay subclass of `Buffer::Client`. Routes buffer commands to remote agents through their `Hosted::Buffer::Relay` WebSocket connections. Overrides `send_command` to use the relay's fire-and-forget method instead of the request/response path. Self-registers as the `:hosted` client on `Buffer`.
+
+Constructor: `initialize(relay_store:)`.
+
+### `Superkick::Hosted::Buffer::Relay` (`hosted/buffer/relay.rb`)
+Server-side relay that bridges server components to a remote agent over a persistent WebSocket connection. In hosted mode, the agent opens a WebSocket to the server, and the server creates a `Relay` for each connected agent. Server-side components send buffer commands through the `Relay`, which forwards them over the WebSocket and waits for the reply (with a 5-second timeout).
+
+Key methods:
+- `attach(websocket)` — called when an agent connects via WebSocket
+- `detach` — called when the WebSocket connection closes; wakes pending waiters
+- `connected?` — returns whether a WebSocket is currently attached
+- `request(command, **params)` — send a command and wait for the response (request/response pattern with `request_id` correlation)
+- `send_command(command, **params)` — fire-and-forget
+- `handle_message(message)` — routes incoming messages to pending request waiters or handles unsolicited agent events (e.g. `injection_result`)
+
+### `Superkick::Hosted::Buffer::RelayStore` (`hosted/buffer/relay_store.rb`)
+Thread-safe registry of `Hosted::Buffer::Relay` instances, one per connected agent. Created at server startup in hosted mode and passed to `Hosted::Buffer::Client`.
+
+Key methods:
+- `get_or_create(agent_id)` — get or create a relay for the given agent
+- `get(agent_id)` — get an existing relay (nil if none)
+- `remove(agent_id)` — remove a relay when the agent disconnects permanently
+
+### `Superkick::Hosted::Bridge` (`hosted/bridge.rb`)
+Abstract base class for agent-side WebSocket bridges that connect local agent components to the hosted server over a persistent WebSocket. Provides shared WebSocket lifecycle: TCP/TLS connect, auth handshake, read loop, and reconnection with exponential backoff.
+
+Uses a **raw WebSocket protocol** (NOT ActionCable):
+1. Client connects to a WebSocket endpoint
+2. Client sends auth JSON text frame: `{"type":"auth","agent_id":"...","api_key":"..."}`
+3. Server responds: `{"type":"welcome"}` or `{"type":"error","message":"..."}`
+4. After auth, data frames flow (text or binary depending on channel)
+
+Uses the `websocket-driver` gem for WebSocket framing. Constants: `RECONNECT_DELAYS = [1, 2, 4, 8, 16, 30]`, `PING_INTERVAL = 30`.
+
+Constructor: `initialize(agent_id:, server_url:, api_key:)`.
+
+Key methods:
+- `start` — start the bridge in a background thread
+- `stop` — cleanly close the connection and stop reconnecting
+
+Subclass hooks (override as needed):
+- `websocket_path` → URL path (e.g. `"/api/v1/agents/#{@agent_id}/buffer/ws"`)
+- `channel_name` → log tag (e.g. `"buffer:ws"`)
+- `handle_server_message(message)` → process parsed JSON text messages
+- `handle_binary_message(data)` → process binary messages (optional)
+- `on_authenticated` → called after welcome (optional)
+
+Sending helpers for subclasses: `send_text(data)`, `send_binary(data)`.
+
+Contains `SocketWrapper` inner class that `websocket-driver` requires (responds to `#url` and `#write`).
+
+### `Superkick::Hosted::Buffer::Bridge` (`hosted/buffer/bridge.rb`)
+Subclass of `Superkick::Hosted::Bridge`. Agent-side bridge that connects the local `Buffer::Server` to the hosted server. Commands from the server arrive as JSON text frames and are dispatched to a `command_handler` (which delegates to the local `Buffer::Server` command handlers). Responses flow back the same way.
+
+Constructor: `initialize(agent_id:, server_url:, api_key:, command_handler:)`.
+
+### `Superkick::Attach::Protocol` (`attach/protocol.rb`)
+Binary frame protocol for the attach system. Defines frame types: OUTPUT, INPUT, META, RESIZE, HISTORY, ERROR, HELLO, COMMAND, NOTIFY.
+
+### `Superkick::Attach::Server` (`attach/server.rb`)
+Per-agent attach endpoint with RW exclusivity, force-takeover, idle timeout, and broadcast callbacks.
+
+### `Superkick::Attach::Client` (`attach/client.rb`)
+Default Unix socket implementation for CLI-side attach sessions. Contains session logic (escape detection, raw terminal mode, output streaming, keystroke forwarding). Wraps a `UNIXSocket` with `Attach::Protocol` binary framing and connects eagerly in the constructor.
+
+The `Attach` module extends `ClientRegistry` and provides `Attach.client_from(agent_id:, config:, mode:, escape_key:, force:)` — returns an `Attach::Client` (Unix socket) for `:local` server type, or the registered hosted client for `:hosted`. Hosted subclasses register via `Attach.register_client(:hosted, klass)`.
+
+Constructor: `initialize(socket_path:, mode:, escape_key:, force:)` — stores session parameters and connects to the Unix socket.
+
+Key methods:
+- `run` — blocking session loop. Returns exit code (0 on clean detach, 1 on error).
+- `read_frame` — read one `Attach::Protocol` frame
+- `write_frame(type, data)` — write one `Attach::Protocol` frame
+- `write_json_frame(type, hash)` — write a JSON-encoded frame
+- `close` — close the underlying connection
+
+### `Superkick::Hosted::Attach::Client` (`hosted/attach/client.rb`)
+WebSocket subclass of `Attach::Client`. Connects to the hosted server, authenticates via the raw WebSocket auth handshake (same as `Hosted::Bridge`), then streams `Attach::Protocol` binary frames over WebSocket messages. Uses a background reader thread and a `Queue` for frame buffering. Self-registers as the `:hosted` client on `Attach`.
+
+Constructor: `initialize(server_url:, api_key:, agent_id:, **session_args)`.
+
+Contains `SocketWrapper` inner class that `websocket-driver` requires.
+
+### `Superkick::Hosted::Attach::Relay` (`hosted/attach/relay.rb`)
+Server-side relay/mux for remote attach sessions over raw WebSocket. Manages one agent WebSocket and multiple user WebSockets, routing `Attach::Protocol` binary frames between them. The relay enforces RW exclusivity, buffers output for replay on new connections, and handles idle timeout auto-demotion.
+
+WebSocket objects must respond to `#send_binary(data)` and `#close`. The relay is transport-agnostic — the hosted server wraps its WebSocket library to provide this interface.
+
+Constructor: `initialize(agent_id:, config: {})`. Config keys: `replay_buffer_size` (default 65536), `max_connections` (default 10), `rw_idle_timeout` (default 300).
+
+Key methods:
+- `attach_agent(websocket)` — called when the agent connects via WebSocket
+- `detach_agent` — called when the agent WebSocket closes; notifies all users with an ERROR frame
+- `agent_connected?` — returns whether an agent WebSocket is attached
+- `add_user(websocket, mode:, force: false)` — add a user connection; enforces RW exclusivity and max connections; sends META frame and replays history
+- `remove_user(websocket)` — remove a user connection
+- `handle_agent_frame(data)` — route a binary frame from the agent (buffers OUTPUT in history, broadcasts to all users)
+- `handle_user_frame(websocket, data)` — route a binary frame from a user (INPUT/RESIZE forwarded to agent for RW user only; COMMAND handled locally for mode switching)
+- `stop` — kill the idle check thread
+- `user_count` — number of connected users
+- `rw_user` — the current RW user websocket (or nil)
+
+COMMAND handling: `promote_rw`, `force_promote_rw`, `demote_ro` are handled locally within the relay. `claim` and `unclaim` are forwarded to the agent.
+
+### `Superkick::Hosted::Attach::RelayStore` (`hosted/attach/relay_store.rb`)
+Thread-safe registry of `Hosted::Attach::Relay` instances, one per agent. Created at server startup and passed to `Control::Server`. The hosted server wires WebSocket connections to relays via `get_or_create` on agent connect and `remove` on permanent disconnect.
+
+Constructor: `initialize(config: {})`. Config is passed through to each relay.
+
+Key methods:
+- `get_or_create(agent_id)` — get or create a relay for the given agent
+- `get(agent_id)` — get an existing relay (nil if none)
+- `remove(agent_id)` — remove and stop a relay when the agent disconnects permanently
+- `each(&block)` — iterate over all relays
+- `size` — number of relays
+
+### `Superkick::Hosted::Attach::Bridge` (`hosted/attach/bridge.rb`)
+Subclass of `Superkick::Hosted::Bridge`. Agent-side bridge that connects the local `Attach::Server` to the hosted server over a persistent WebSocket for streaming PTY output to remote attach users.
+
+Output forwarding: registers a broadcast callback on `Attach::Server` via `on_authenticated` so that PTY output is forwarded to the relay as OUTPUT frames.
+
+Remote input: binary WebSocket messages from the relay (INPUT/RESIZE frames from remote users) are dispatched to `Attach::Server#handle_remote_input`.
+
+Constructor: `initialize(agent_id:, server_url:, api_key:, attach_server:)`.
+
+WebSocket path: `/api/v1/agents/#{agent_id}/attach/agent/ws`.
+
+### `Superkick::Hosted::McpProxy` (`hosted/mcp_proxy.rb`)
+Transparent stdio-to-HTTP proxy for hosted mode. In hosted mode, `superkick mcp start` launches this instead of `McpServer`. Reads JSON-RPC lines from stdin and POSTs them to `{server_url}/api/v1/mcp` with `Authorization: Bearer {api_key}` and `X-Superkick-Agent-Id: {agent_id}` headers. Writes responses back to stdout.
+
+The AI CLI sees a normal stdio MCP server — it has no idea it's talking to a remote endpoint. This avoids teaching every driver about remote MCP URL configuration.
+
+Handles three HTTP response types:
+- `application/json` — single JSON-RPC response, written as one line to stdout
+- `text/event-stream` — SSE stream, each `message` event data written as a line
+- `202 Accepted` — notification acknowledged, nothing written
+
+Error handling: on HTTP errors, connection failures, or timeouts, returns a JSON-RPC error response (code `-32603`) for requests (messages with `id`). Notifications (no `id`) are silently dropped on error.
+
+Tracks `Mcp-Session-Id` from server responses and sends it back on subsequent requests.
+
+Constructor: `initialize(connection: nil)`. Reads `SUPERKICK_AGENT_ID` from the environment (same as `McpServer`). Reads server URL and API key from `Superkick.config.server`. The `connection:` parameter accepts a pre-built Faraday connection for test injection.
+
+### `Superkick::InputBuffer` (`input_buffer.rb`)
+Tracks the user's partial input (characters typed since the last Enter) and manages named injection guards. Guards are set by `update_guards` when output matches a guard pattern; they block injection until cleared (either on submit or manually).
+
+### `Superkick::InjectionQueue` (`injection_queue.rb`)
+Agent-side queue that manages injection precondition checks and PTY writes locally, eliminating network round-trips between server and agent. Entries have TTL, supersede-by-key, and priority semantics.
+
+Three priority levels:
+- `:high` — spawn kickoff prompts (processed first)
+- `:normal` — monitor events (default)
+- `:low` — cost polling injections
+
+Constructor requires `pty_proxy:`, `idle_threshold:`, and `inject_clear_delay:` — config values are injected by `PtyProxy` at construction time (no direct `Superkick.config` access).
+
+The drain loop runs agent-side, checking idle state and guards locally with zero network latency. When an injection succeeds or is skipped/expired, the queue reports the result back to the server via `injection_result` IPC so the server can fire notifications.
+
+Constants: `MAX_SIZE = 50`, `DEFAULT_TTL = 300` seconds. Entries that exceed TTL are silently expired. When the queue is full, lowest-priority entries are evicted.
+
+### `Superkick::Injector` (`injector.rb`)
+Orchestrates one injection attempt:
+1. Checks agent is reachable via `Buffer::Client`
+2. Renders Liquid template via `TemplateRenderer`
+3. Sends `enqueue_injection` to the agent via `Buffer::Client` (fire-and-forget)
+4. Returns `:enqueued` or `:skipped` (no longer checks gates or writes to PTY directly)
+
+Accepts a `buffer_client:` constructor parameter for transport-agnostic buffer communication. The actual precondition checks (idle state, guards) and PTY writes are handled agent-side by `InjectionQueue`. Notification dispatch happens asynchronously when the agent reports injection results back via IPC.
+
+**Event-level injection hints:** Monitors can include optional keys in the event hash to control queue behavior:
+- `injection_priority` — `:high`, `:normal` (default), or `:low`
+- `injection_ttl` — seconds before the entry expires (overrides the per-monitor `injection_ttl` config)
+- `injection_supersede_key` — custom key for supersede semantics (defaults to `monitor_name`)
+
+Built-in events with non-default hints:
+
+| Event | Priority | TTL | Supersede key |
+|-------|----------|-----|---------------|
+| `ci_success` (GitHub, CircleCI) | `:normal` | 60s | `"ci_status"` |
+| `ci_failure` (GitHub, CircleCI) | `:normal` | 300s | `"ci_status"` |
+| `pr_review` (CHANGES_REQUESTED) | `:high` | 300s | default |
+| `story_blocker` | `:high` | 300s | `"story_blocker_status"` |
+| `story_unblocked` | `:normal` | 120s | `"story_blocker_status"` |
+| `shell_success` | `:normal` | 60s | default |
+| `team_digest` | `:normal` | 120s | default |
+| `team_digest` (with blockers) | `:high` | 120s | default |
+| `teammate_message` | `:high` | 900s | default |
+| `slack_reply` | `:high` | 900s | default |
+
+### `Superkick::Notifier` (`notifier.rb`)
+Abstract base class for notification channels. Notifications fire on two kinds of events:
+1. **Monitor injections** — from `Injector` after a successful injection
+2. **Agent lifecycle events** — from `Supervisor`/`Spawn::AgentSpawner` when spawned agents change state
+
+Each notifier is isolated — one failure doesn't prevent others from firing.
+
+Subclasses implement:
+- `self.type` → unique Symbol (e.g. `:terminal_bell`, `:command`)
+- `self.templates_dir` → (optional) path to bundled Liquid templates directory (default `nil`)
+- `notify(payload)` → called with a Hash containing `event_type`, `monitor_type`, `monitor_name`, `agent_id`, `message`, and `rendered_prompt`
+- `stateful?` → (optional) return `true` if this notifier tracks state across events. Stateful notifiers persist for the server's lifetime and receive `agent_finished` callbacks.
+- `agent_finished(agent_id:)` → (optional) called when an agent's event stream is definitively over. Stateful notifiers use this to clean up per-agent state.
+- `self.setup_label` → (optional) short name for the `superkick setup` wizard
+- `self.setup_config` → (optional) YAML snippet string for config generation
+
+**Template support:** Notifiers that include the `Superkick::Liquid` DSL can use structured templates with block tags, bodyless tags, and accumulators. Two instance methods are provided:
+- `render_notification(payload)` → resolves a template via `TemplateRenderer.resolve_notification`, renders it with the notifier's `Liquid::Environment` (including any `liquid do` filters/blocks/tags), and returns a `NotifierTemplate::Result`. Returns `nil` if no template is found. Context fields from the payload are promoted to top-level template assigns, so templates use `{{ team.id }}` rather than `{{ context.team.id }}`.
+- `build_accumulator` → constructs the accumulator for block tag rendering. Returns a `context_class` instance if defined via `liquid do`, otherwise an empty Hash.
+
+The `liquid do` DSL supports three tag primitives:
+- `block :name do |ctx, text, attrs| ... end` — declares a Liquid block tag (`{% name %}...{% endname %}`). The handler receives the accumulator, rendered body text, and parsed attributes.
+- `tag :name do |ctx, attrs| ... end` — declares a bodyless Liquid tag (`{% name %}`). The handler receives the accumulator and parsed attributes (no body, no end tag).
+- `filter :name do |input, ...| ... end` — declares a Liquid filter.
+
+Attribute values are resolved as Liquid expressions at render time (matching Liquid's built-in `{% render %}` tag): quoted values (`key: "literal"`) stay as literal strings, bare identifiers (`key: my_url`) are resolved from the template context, and dotted paths (`key: issue.url`) traverse nested objects and Drops. Undefined variables are omitted from the attributes hash.
+
+Registry follows the same pattern as Driver and Monitor:
+```ruby
+Superkick::Notifier.register(MyNotifier)
+Superkick::Notifier.lookup(:my_notifier)
+Superkick::Notifier.registered
+```
+
+**Lifecycle event types** (`Notifier::LIFECYCLE_EVENTS`):
+- `agent_spawned` — a new agent was started by a spawner
+- `agent_completed` — a spawned agent reached its goal
+- `agent_failed` — a spawned agent's goal failed
+- `agent_timed_out` — a spawned agent hit `max_duration`
+- `agent_blocked` — the AI signaled it needs help (errored status)
+- `agent_stalled` — a spawned agent has been idle past the stall threshold
+- `agent_terminated` — a spawned agent was manually stopped
+- `agent_claimed` — a user claimed a spawned agent for manual intervention
+- `agent_unclaimed` — a user released a claimed agent back to autonomous operation
+- `agent_pending_approval` — a spawn requires approval before proceeding
+- `workflow_triggered` — a workflow spawn was fired after a goal reached a terminal status
+- `workflow_iterations_exceeded` — a workflow spawn was blocked because the target spawner reached its `max_iterations` limit
+- `budget_warning` — an agent's cost is approaching its budget limit
+- `budget_exceeded` — an agent's cost has exceeded its budget limit
+- `team_created` — a new team was created (fires when a team lead agent is spawned)
+- `team_completed` — a team's lead agent completed its goal (all team members terminated)
+- `team_failed` — a team's lead agent failed (all team members terminated)
+- `team_timed_out` — a team's lead agent exceeded `max_duration` (all team members terminated)
+- `worker_spawned` — a worker agent was spawned by a team lead via `superkick_spawn_worker`
+- `teammate_message` — a team member sent a direct message to another teammate
+- `teammate_blocker` — a team member reported a blocker via `superkick_post_update`
+- `attach_promoted` — an attach client was promoted to read-write mode
+- `attach_demoted` — an attach client was demoted to read-only mode
+- `attach_idle_timeout` — an attach client was demoted due to idle timeout
+- `attach_force_takeover` — an attach client's read-write was taken over by another client
+- `agent_update` — a team member posted a status update via `superkick_post_update`
+- `artifact_published` — a team member published an artifact via `superkick_publish_artifact`
+
+Built-in notifiers:
+- **`TerminalBell`** (`:terminal_bell`) — writes BEL (`\a`) to stderr. Zero-config default. Most terminals respond with a visual or audible alert.
+- **`Command`** (`:command`) — runs a shell command via `ProcessRunner.spawn`. Event details are passed as `SUPERKICK_*` environment variables (`SUPERKICK_EVENT_TYPE`, `SUPERKICK_MONITOR_TYPE`, `SUPERKICK_MONITOR_NAME`, `SUPERKICK_AGENT_ID`, `SUPERKICK_MESSAGE`). Supports notification templates with an `{% env key: "name" %}` block tag that populates additional `SUPERKICK_<NAME>` env vars (uppercased, auto-prefixed). Text outside `{% env %}` blocks becomes `SUPERKICK_BODY`. When no template exists, `SUPERKICK_BODY` is not set. No bundled templates — users create per-event templates at `~/.superkick/templates/notifications/command/<event_type>.liquid`. Commands are killed after `timeout_seconds` (default 10).
+- **`Integrations::Slack::Notifier`** (`:slack`) — posts a rich Block Kit message to Slack. Supports two authentication modes: **Incoming Webhook** (`webhook_url:`) for single-channel zero-token setup, and **Web API** (`token:` + `channel:`) for dynamic channel targeting via `chat.postMessage`. Block Kit structure is defined via Liquid templates with custom block tags and bodyless tags covering all Block Kit block types. **Block tags** (have body content): `{% header %}` (plain text, emoji-enabled), `{% section %}` (mrkdwn), `{% context %}` (mrkdwn metadata), `{% image url: "..." alt_text: "..." %}` (body becomes optional title), `{% button url: "..." style: "primary" %}` (auto-groups consecutive buttons into an actions block), `{% fields %}` (each non-empty line becomes a mrkdwn field in a section), `{% rich_text %}` (body becomes text in a rich_text_section), `{% video url: "..." thumbnail_url: "..." alt_text: "..." %}` (body becomes title), `{% input action_id: "..." type: "plain_text_input" placeholder: "..." %}` (body becomes label, supports `dispatch_action: "true"`). **Bodyless tags** (self-closing, no end tag): `{% divider %}` (horizontal rule), `{% file external_id: "..." %}` (source defaults to `"remote"`). **Filters:** `event_emoji`, `format_title`, `join_present`. The `event_emoji` filter resolves emoji in three tiers: explicit `EMOJI_MAP` lookup, then keyword substring matching (e.g. `deployment_completed` matches `completed` → `:white_check_mark:`), then `:bell:` default. The bundled `default.liquid` template produces a header with event emoji, a section with the message body, and a context block with agent/monitor/team metadata. Users can override per-event or globally at `~/.superkick/templates/notifications/slack/`. **Stateful in API mode** — tracks `thread_ts` per thread key. When an agent has a `team_id` in its context, messages are threaded by team (all agents in the same team share a thread). Otherwise, messages are threaded by agent. Webhook mode is stateless (Slack webhooks don't return a `ts`). Accepts an optional `thread_ts:` constructor parameter (`@initial_thread_ts`) that pre-seeds thread correlation — when no `thread_ts` exists in the state store and no `seed_thread_ts` from payload context, falls back to `@initial_thread_ts`. This is used by the `_spawn_notifiers` mechanism to create per-agent Slack notifiers that thread under a specific message. Uses Faraday for HTTP (already a dependency). Config: `webhook_url` or `token` + `channel`.
+- **`Integrations::Datadog::Notifier`** (`:datadog`) — sends events and metrics to Datadog via DogStatsD (UDP). Events appear in the Event Explorer; metrics (`<prefix>.event` counter, `<prefix>.agent.duration` gauge, `<prefix>.agent.cost_usd` gauge) appear in Metrics Explorer. **Tag cardinality is managed**: events include all tags (`agent_id`, `team_id`, `event_type`, `monitor_type`, `monitor_name`, `team_role`, `spawner_name`), while metrics use only low-cardinality tags (`event_type`, `monitor_type`, `monitor_name`, `team_role`, `spawner_name`) to avoid billing explosions from unbounded dimensions. **Stateful** — tracks `spawned_at` per agent to compute duration on terminal events (also uses `spawned_at` from context when available). Alert type mappings: terminal events → `"error"`, warning events → `"warning"`, informational events (`agent_update`, `artifact_published`, `agent_spawned`, `worker_spawned`, etc.) → `"info"`. No gem dependency — uses raw UDP datagrams in the standard DogStatsD protocol. Config: `statsd_host` (default `"localhost"`), `statsd_port` (default `8125`), `prefix` (default `"superkick"`), `tags` (array of global tags).
+- **`Integrations::Honeybadger::Notifier`** (`:honeybadger`) — sends structured events to Honeybadger Insights via the Events API (HTTP). Events include `event_type`, `agent_id`, `severity` (mapped from event type), `message`, monitor metadata, `duration_seconds` on terminal events, plus context fields (`team_id`, `team_role`, `spawner_name`, `cost_usd`) when available. Uses the payload `timestamp` as the event timestamp. Severity mappings: terminal failure events → `"error"`, warning events → `"warning"`, informational events (`agent_update`, `artifact_published`, `agent_spawned`, `worker_spawned`, etc.) → `"info"`. **Stateful** — tracks `spawned_at` per agent to compute duration (also uses `spawned_at` from context when available). Uses Faraday for HTTP (already a dependency). Config: `api_key` (required), `tags` (array of optional tags).
+
+Configuration (in `config.yml`):
+```yaml
+notifications:
+  - type: terminal_bell
+  - type: command
+    run: "notify-send 'Superkick' '$SUPERKICK_MESSAGE'"
+    events:                          # optional — restricts which events fire
+      - agent_blocked
+      - agent_completed
+  - type: slack
+    webhook_url: <%= env("SLACK_WEBHOOK_URL") %>
+  - type: slack
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    channel: "#superkick-notifications"
+    events:
+      - agent_completed
+      - agent_failed
+      - agent_blocked
+  - type: datadog
+    statsd_host: localhost
+    statsd_port: 8125
+    prefix: superkick
+    tags:
+      - "env:production"
+  - type: honeybadger
+    api_key: <%= env("HONEYBADGER_API_KEY") %>
+    tags:
+      - production
+```
+
+When `notifications` is empty or absent, defaults to `[{ type: terminal_bell }]`. When `events:` is absent on a notifier, it receives all events.
+
+### `Superkick::NotifierStateStore` (`notifier_state_store.rb`)
+Injectable key-value state storage for stateful notifiers. Stateful notifiers (Slack, Datadog, Honeybadger) track per-agent state across events (e.g. Slack `thread_ts` for threading, `spawned_at` for duration computation). This class provides an explicit interface for that state, enabling the hosted Rails app to provide a database-backed implementation.
+
+Interface:
+- `get(notifier_type, key)` → Hash or nil
+- `put(notifier_type, key, data)` → void (upsert)
+- `delete(notifier_type, key)` → void
+
+Built-in implementation:
+- **`NotifierStateStore::Memory`** — thread-safe in-memory storage (Mutex-protected nested Hash). Default for local server mode. State is lost on server restart. Created at server startup and passed through `NotificationDispatcher` → each notifier's `state_store:` constructor parameter.
+
+The `Notifier` base class requires `state_store:` in its constructor (no default) and stores it as `@state_store`. The server creates a `NotifierStateStore::Memory` at startup and passes it through; tests must pass it explicitly. Stateful notifiers use `@state_store` instead of managing their own mutex-protected hashes.
+
+### `Superkick::NotificationDispatcher` (`notification_dispatcher.rb`)
+Holds long-lived notifier instances so stateful notifiers can track per-agent state across events (e.g. Slack `thread_ts` for threading). Created once at server startup and passed to all server-side components via constructor injection.
+
+Accepts an optional `store:` keyword (AgentStore) to enrich payloads with agent context. Requires a `state_store:` keyword (`NotifierStateStore`) that is passed through to each notifier instance. Accepts an optional `notifiers:` keyword for test injection of pre-built `[notifier, events_filter]` pairs (bypasses config-based construction). Accepts an optional `internal_notifiers:` keyword — an array of notifier instances that always fire on every event (no event filter). Internal notifiers are used for side-effect notifiers like `Team::LogNotifier` that must see all events regardless of user configuration. When a store is provided, `build_payload` looks up the agent and populates a `context` Hash with team info, spawn info, cost data, and rehydrated event context (Drops like `issue`, `story`, plus scalars like `repo`, `branch`).
+
+Key methods:
+- `dispatch(event:, agent_id:, rendered_prompt:, message:)` → fires both global notifiers and per-agent notifiers in a background thread. After terminal events, automatically calls `agent_finished` on stateful notifiers and cleans up per-agent notifier instances.
+- `agent_finished(agent_id)` → notifies stateful notifiers that an agent's event stream is over, and removes per-agent notifier instances for the agent. Called automatically after terminal events, but can also be called explicitly.
+- `register_agent_notifiers(agent_id)` → builds notifier instances from the agent's notifier configs (stored on the `Agent` object via `_spawn_notifiers`). Per-agent notifiers are stored in `@agent_notifiers` as `{ agent_id => { name => [notifier, events_filter] } }` and fired alongside global notifiers on every dispatch for that agent. Thread-safe via Mutex.
+- `add_agent_notifier(agent_id, name)` → builds and registers a single per-agent notifier by name. Called by `Control::Server` when `superkick_add_notifier` is invoked on a running agent. Looks up the notifier config from the agent's stored configs.
+- `remove_agent_notifier(agent_id, name)` → removes a single per-agent notifier by name. Calls `agent_finished` on stateful notifiers for proper cleanup. Called by `Control::Server` when `superkick_remove_notifier` is invoked.
+
+Terminal event types (`TERMINAL_EVENT_TYPES`): `agent_completed`, `agent_failed`, `agent_timed_out`, `agent_terminated`, `team_completed`, `team_failed`, `team_timed_out`.
+
+Payload structure passed to notifiers:
+```ruby
+{
+  event_type: String,        # e.g. "agent_completed"
+  monitor: MonitorDrop,      # Drop with .name and .type (e.g. "github_issues", "spawner")
+  agent_id: String,          # the affected agent's ID
+  message: String,           # human-readable summary
+  rendered_prompt: String,   # (nil for lifecycle events)
+  timestamp: String,         # ISO 8601 UTC timestamp
+  context: {                 # enriched from agent store + event
+    agent: AgentDrop,        # .id, .role, .team_role, .spawned_at, .cost_usd, .claimed, .goal
+    #   goal: GoalDrop,      #   .status, .summary (nested under agent)
+    team: TeamDrop,          # .id, .members (if any)
+    spawner: SpawnerDrop,    # .name (spawner that created the agent)
+    parent_agent_id: String, # parent in workflow chain
+    workflow_depth: Integer,  # depth in workflow chain
+    repo: String,            # repository from spawn event context
+    branch: String,          # branch from spawn event context
+    issue: IssueDrop,        # GitHub issue (from spawn event context, rehydrated)
+    story: StoryDrop,        # Shortcut story (from spawn event context, rehydrated)
+    budget: Float,           # (budget events only)
+    spent: Float,            # (budget events only)
+    approval_id: String,     # (pending_approval events only)
+    repository_name: String, # (worker_spawned events only)
+    artifact_name: String,   # (artifact_published events only)
+    kind: String,            # (agent_update events only — status/decision/blocker/progress/completed/failed)
+    target_agent_id: String, # (teammate_message events only — directed message recipient)
+    slack_thread_ts: String  # (slack spawner events only — Slack thread timestamp)
+    # ... plus other rehydrated context fields from spawn event
+  }
+}
+```
+
+All context fields are optional — only present when the data is available. Agent-level fields are populated from the store lookup; event-level fields are forwarded from the dispatch event.
+
+The dispatcher is passed via constructor injection (as a required keyword argument) to `Injector`, `Supervisor`, `Control::Server`, `Spawn::AgentSpawner`, `Spawn::Handler`, and `Spawn::WorkflowExecutor`. All these classes have a `dispatch_notification(...)` private helper that delegates to the dispatcher.
+
+### `Superkick::Spawn::ApprovalStore` (`spawn/approval_store.rb`)
+Thread-safe in-memory store for pending spawn approvals and rejection records. When a spawner has `approval_required: true`, the `Spawn::Handler` queues events here instead of spawning immediately. Rejections are persistent (within a server lifetime) to prevent re-dispatching of rejected events.
+
+Key methods:
+- `add(event:, spawner_config:)` → returns approval ID (skips if rejected)
+- `take(id)` / `get(id)` → retrieve (destructive/non-destructive)
+- `reject(id, reason:)` → move from pending to rejected
+- `has_agent?(agent_id)` → true if pending or rejected
+- `clear_rejection(id)` / `clear_all_rejections` → allow re-dispatch
+
+### `Superkick::Team::Log` (`team/log.rb`)
+Append-only shared log for a team of agents. Stored at `~/.superkick/teams/<team_id>.log` as newline-delimited JSON. Thread-safe via Mutex.
+
+Entry schema (`Team::Log::Entry` — `Data.define`):
+- `timestamp` — ISO 8601 UTC with microseconds
+- `category` — one of `CATEGORIES`: `:update`, `:message`, `:lifecycle`, `:system`, `:artifact`
+- `agent_id` — the agent that created this entry
+- `agent_role` — team role of the agent (lead, worker, member)
+- `role` — human-readable role label (optional)
+- `message` — free-text content
+- `kind` — sub-type within the category (e.g. `:blocker`, `:decision`, `:spawned`)
+- `target_agent_id` — recipient agent for messages (optional)
+- `artifact_name` — name of published artifact (optional)
+
+`Entry.from_hash(raw)` builds an Entry from a parsed hash, filling nil defaults for optional fields that were compacted away during persistence and symbolizing `category` and `kind`.
+
+Key methods:
+- `append(agent_id:, agent_role:, category:, message:, **opts)` — validates category, creates entry, persists to disk
+- `entries(since: nil, category: nil)` — filtered entry retrieval
+- `summary` — returns `{ latest_by_agent:, unresolved_blockers: }`
+
+### `Superkick::Team::ArtifactStore` (`team/artifact_store.rb`)
+Per-team persistent artifact storage for sharing data between agents. Artifacts are JSON files at `~/.superkick/teams/<team_id>/artifacts/<author>--<name>.json`. Thread-safe via Mutex.
+
+`Artifact = Data.define(:name, :author, :content, :created_at, :updated_at)`
+
+Key methods:
+- `publish(team_id:, author:, name:, content:)` → creates or updates, returns `Artifact`
+- `get(team_id:, author:, name:)` → returns `Artifact` or `nil`
+- `list(team_id:, author: nil)` → metadata array (no content)
+- `delete(team_id:, author:, name:)` → returns boolean
+
+### `Superkick::Team::LogMonitor` (`team/log_monitor.rb`)
+Registered monitor (`:team_log`) that polls the team log and injects digest summaries of teammate activity. Auto-added for team leads (via `_spawn_monitors` in `Spawn::Handler#enrich_for_team`), workers (via `_spawn_monitors` in `Control::Server#cmd_spawn_worker`), and human team members (inline in `Control::Server#cmd_register`).
+
+On each tick:
+1. Reads team log entries since last check
+2. Filters out self-entries (no self-echo)
+3. Groups remaining entries by category
+4. Dispatches `team_digest` event with batched entries and blocker flag
+
+Config: `team_id` (required), `team_log_store` (injected by server).
+
+### `Superkick::Team::LogNotifier` (`team/log_notifier.rb`)
+Internal notifier (type `:team_log`) that writes team log entries as a notification side-effect. Wired as an internal notifier via the `internal_notifiers:` parameter on `NotificationDispatcher`, so it fires on every event regardless of user-configured event filters. When the dispatched event's agent belongs to a team, the notifier writes a log entry to the team's `Team::Log`. Handles lifecycle events (e.g. `agent_spawned`, `agent_completed`), update events (`agent_update`), message events (`teammate_message`), and artifact events (`artifact_published`) by mapping them to the appropriate team log categories and kinds. This replaces the ad-hoc team log writes that were previously scattered across `Control::Server` and `Spawn::AgentSpawner`.
+
+### `Superkick::Spawn::WorkflowValidator` (`spawn/workflow_validator.rb`)
+Static validation for spawner workflow configs. Performs two checks at server startup:
+
+1. **Cycle detection** — walks `on_complete:` and `on_fail:` spawner reference chains looking for cycles via visited-set tracking. Only `:spawner` references create chain links — inline configs are leaf nodes.
+2. **Cyclic iteration requirement** — checks that spawners with `allow_cycles: true` have `max_iterations` set. Without an iteration limit, cyclic workflows would run forever. Spawners that fail this check are disabled with an error at startup.
+
+Class methods:
+- `Spawn::WorkflowValidator.validate(spawners)` → returns list of cycles (empty = valid)
+- `Spawn::WorkflowValidator.cyclic_spawners_without_iteration_limit(spawners)` → returns list of spawner names (Symbols) that have `allow_cycles: true` but no `max_iterations`
+
+### `Superkick::Spawn::WorkflowExecutor` (`spawn/workflow_executor.rb`)
+Resolves workflow config, builds enriched events, handles VCS ownership transfer, enforces depth limits, and dispatches workflow spawns. Called by Supervisor when a spawned agent's goal reaches a terminal status.
+
+Key method:
+- `fire(agent_id:, goal_status:, spawner_config:)` — triggers workflow spawn if `on_complete:` or `on_fail:` is configured
+
+Workflow config supports two forms:
+1. **Spawner reference** — `{ spawner: :review_pr }` — resolves from `Superkick.config.spawners`
+2. **Inline config** — `{ goal: { type: :agent_signal }, driver: "claude_code" }` — fills in defaults from parent
+
+**Execution sequence:**
+1. Determine hook key from goal status (`:completed` → `:on_complete`, `:failed` → `:on_fail`; `:timed_out` triggers neither)
+2. Resolve config — spawner references are looked up from `Superkick.config.spawners`; inline configs inherit `driver` and `max_duration` from parent
+3. Check iteration limit — `workflow_iterations[target_name]` from parent's spawn_info vs target spawner's `max_iterations`
+4. Build enriched event — forward serialized context from parent's `spawn_info[:context]` wholesale (replaces the old `FORWARDED_FIELDS` approach), stamp `workflow_depth`, `workflow_iterations`, `parent_agent_id`, `parent_goal_status`, and `parent_goal_summary` (from the parent agent's `goal_summary`, when available — provides failure retrospective context for retry workflows). Also forwards parent's per-agent notifier configs as `_spawn_notifiers` when the parent agent has notifier configs, so workflow children inherit per-agent notifiers.
+5. Transfer VCS state — when no `repository:` key, call `agent_spawner.take_vcs_state(agent_id)` to hand the parent's VCS state (adapter + destination) to the child.
+6. Fire `workflow_triggered` notification
+7. Spawn in a background thread via `agent_spawner.spawn`
+9. On spawn failure, reclaim inherited VCS state (teardown) to avoid orphaned workspaces
+
+**Event enrichment — context forwarding:**
+The parent agent's `spawn_info[:context]` is forwarded wholesale to the child workflow event. This carries all integration-specific data (Drops like `issue`, `story`, plus scalars like `repo`, `branch`) without enumerating field names. Context is serialized with `_drop_type` markers so Drops survive the round-trip and are available in workflow templates as `{{ issue.title }}`, `{{ story.ref }}`, etc. Per-agent notifier configs (from `_spawn_notifiers`) are also forwarded when present on the parent agent, ensuring workflow children inherit the same per-agent notification channels.
+
+This ensures workflow templates have access to the full context chain — a review agent knows which issue it's reviewing, which branch to check, etc.
+
+**VCS inheritance modes:**
+- **Inherit (default)** — no `repository:` key → parent's VCS state is transferred via `take_vcs_state`. Parent skips teardown; child cleans up on exit.
+- **New repository** — explicit `repository:` key → child gets its own VCS setup. Parent tears down normally.
+
+Configuration (in spawner config):
+```yaml
+spawners:
+  implement:
+    type: github_issues
+    on_complete:
+      spawner: review_pr          # reference to another spawner
+    on_fail:
+      goal:                       # inline config (agent_signal is the default, shown here for clarity)
+        type: agent_signal
+      prompt_template: fix_and_retry
+    max_iterations: 3             # max times this spawner can fire per chain (required for allow_cycles)
+```
+
+### `Superkick::CostAccumulator` (`cost_accumulator.rb`)
+Thread-safe per-agent cost tracking data model. Stored on each `Agent` object as `agent.cost`. Records token counts (in/out), USD cost, and a capped sample history (max 100 samples).
+
+Key methods:
+- `record(tokens_in:, tokens_out:, cost_usd:, source:)` — add a cost sample (thread-safe via Mutex)
+- `to_h` — returns `{ total_tokens_in:, total_tokens_out:, total_cost_usd:, sample_count: }`
+- `last_sample_at` — timestamp of most recent sample (for staleness checks)
+- `samples` — array of all recorded samples (newest last)
+
+### `Superkick::CostExtractor` (`cost_extractor.rb`)
+Line-buffered PTY output parser that matches complete lines against driver-specific `CostPattern` arrays. Handles cumulative-to-delta conversion — AI CLIs typically report cumulative totals (e.g. "Total cost: $1.50"), so the extractor tracks previous values and computes incremental deltas to avoid double-counting on status-bar refreshes.
+
+Key methods:
+- `initialize(patterns:)` — takes an Array of `CostPattern` objects from the driver
+- `feed(text)` — buffer text, process complete lines, return Array of cost delta Hashes
+
+The internal line buffer is capped at `MAX_BUFFER` (1024 bytes) to prevent unbounded memory growth from binary output.
+
+### `Superkick::CostPattern` (defined in `driver.rb`)
+`Data.define(:pattern, :extractor)` — pairs a Regexp with a lambda that extracts cost data from a MatchData. Drivers return arrays of these from `cost_patterns`.
+
+```ruby
+CostPattern.new(
+  pattern: /Total cost:\s*\$([0-9]+\.?[0-9]*)/,
+  extractor: ->(m) { { cost_usd: m[1].to_f } }
+)
+```
+
+### Driver config helpers (class methods on `Superkick::Driver`)
+
+Three class methods on `Driver` handle driver config normalization, profile resolution, and merging across the spawner/team/workflow cascade:
+
+- `Driver.normalize_driver(driver, profile_source: nil)` — normalizes a polymorphic `driver` value to a Hash. Strings/Symbols become `{ type: :name }`. Hashes are normalized (`:type` symbolized). When the Hash contains a `:profile` key and a `profile_source` is provided, the named profile is resolved from the source and used as the base, with any remaining inline keys merged on top.
+
+- `Driver.merge_driver(base, override)` — deep-merges two driver config values. When the override is a String/Symbol, it completely replaces the base (no merge). When both are Hashes: scalar keys (`type`, `config_dir`, `command`) — override wins; `args` — arrays are concatenated (base first); `env` — hashes are merged (override keys win).
+
+- `driver.apply_config_dir(config_dir, env:, args:)` — instance method. Applies a `config_dir` override to the spawned process environment and args. Each driver knows how its CLI accepts a settings directory override. Built-in implementations: ClaudeCode sets `CLAUDE_CONFIG_DIR`, Copilot sets `COPILOT_HOME`, Codex sets `CODEX_HOME`, Gemini sets `GEMINI_CLI_HOME`, Goose sets `GOOSE_CONFIG_DIR`.
+
+### `Superkick::Driver::ProfileSource` (`driver/profile_source.rb`)
+Abstract base class for named driver profile sources. A profile is a named, reusable set of driver configuration options (type, config_dir, command, args, env) that can be referenced by name from spawner configs via `driver: { profile: :review }`.
+
+Follows the same registry + build pattern as `RepositorySource`:
+- `ProfileSource.build(config)` — builds a source from a profiles config hash. Currently always builds a `StaticProfileSource`.
+- `ProfileSource.register(source_class)` / `ProfileSource.lookup(name)` / `ProfileSource.registered` — standard registry pattern.
+
+Subclass contract:
+- `self.type` → unique Symbol
+- `get(name)` → profile Hash or nil
+- `list` → Hash of `{ name_sym => profile Hash }`
+
+### `Superkick::Driver::StaticProfileSource` (`driver/profile_source.rb`)
+Profiles defined inline in the YAML config under `drivers.profiles`. Each key is a profile name, each value is a driver config hash.
+
+Profile Hash structure:
+```ruby
+{ name: :review, type: :claude_code,
+  config_dir: "~/.superkick/driver-configs/review/.claude",
+  command: "/opt/bin/claude",
+  args: ["--verbose"],
+  env: { "ANTHROPIC_API_KEY" => "sk-review" } }
+```
+
+Normalizes on construction: expands `config_dir` paths, symbolizes `type`, wraps `args` into an array.
+
+### `Superkick::BudgetChecker` (`budget_checker.rb`)
+Centralized multi-level budget evaluation. Checks three levels of budget constraints and returns an array of violation Hashes.
+
+Budget levels (all three support `warning_threshold_percentage`, default 80):
+1. **Agent-level** — per-spawner `budget.per_agent.max_cost_usd`. Warns at threshold percentage. Exceeded when agent cost > max.
+2. **Spawner-level** — `budget.max_cost_usd`. Sums cost across all agents from the same spawner within `budget.window_hours`. Warns at threshold percentage.
+3. **Global** — top-level `budget.max_cost_usd`. Sums cost across all agents within `budget.window_hours`. Warns at threshold percentage.
+
+Violation Hash format: `{ level: :agent|:spawner|:global, budget:, spent:, action: :warning|:exceeded }`
+
+Only checks spawned agents (agents with `spawn_info`). Interactive agents are always exempt.
+
+### `Superkick::CostPoller` (`cost_poller.rb`)
+Background thread that periodically injects the driver's cost command (e.g. `/cost`, `/stats`) into idle headless agents when their cost data goes stale. Only runs for spawned agents — interactive agents have a human who can type the command themselves.
+
+Configuration:
+- `interval` — check frequency (default 300s / 5 min, configurable via `cost_poll_interval`)
+- `stale_after` — cost data staleness threshold (default 600s / 10 min, configurable via `cost_stale_after`)
+
+Uses the `enqueue_injection` buffer command with `:low` priority to submit cost commands to the agent-side `InjectionQueue`. Precondition checks (guards, idle state) are handled agent-side by the queue.
+
+### `Superkick::ProcessRunner` (`process_runner.rb`)
+Unified subprocess execution with reliable timeouts. Avoids Ruby's `Timeout.timeout` (which cannot reliably interrupt C-level blocking calls). Used by the `Command` notifier and the `Integrations::Shell::Monitor`.
+
+Two entry points:
+- `.run(cmd, timeout:, env:, chdir:)` — captures stdout+stderr, returns `{ output:, status:, timed_out: }`
+- `.spawn(cmd, timeout:, env:)` — fire-and-forget (no output capture), returns `{ status:, timed_out: }`
+
+Both methods SIGTERM the child on timeout and reap it to prevent zombies. Timeouts use `CLOCK_MONOTONIC`.
+
+### `Superkick::Poller` (`poller.rb`)
+Abstract base class for all polling event sources. Provides the shared run loop, error handling, config validation, and backoff logic used by both `Monitor` and `Spawner`.
+
+Subclasses implement:
+- `self.type` → Symbol (unique, e.g. `:github`)
+- `self.required_config` → Array of required config key Symbols (e.g. `%i[branch repo]`)
+- `tick` → called each `poll_interval`
+- `self.setup_label` → String or nil (short name for setup wizard, optional)
+- `self.setup_config` → String or nil (YAML snippet for config generation, optional)
+
+The `run` loop handles `RateLimited` (backs off), `FatalError` (stops the thread), and generic errors (logs + backs off by `error_backoff`).
+
+Exception classes: `Poller::RateLimited`, `Poller::FatalError`.
+
+### `Superkick::Monitor` (`monitor.rb`)
+Extends `Poller` for agent-bound monitors. Subclasses also implement:
+- `self.templates_dir` → path to Liquid templates (or nil)
+- `self.resolve_config(config, environment: {})` → fills in missing config keys from the environment snapshot (default: returns config unchanged)
+- `tick` → called each `poll_interval`; call `dispatch(event_hash)` to emit
+
+Constructor: `initialize(name:, config:, handler:, agent: nil, server_context: {})`. The `server_context` Hash carries server-side dependencies (like `team_log_store`) that are not serializable config — they are injected by the server when building monitors and kept separate from the persisted `config` hash.
+
+Each instance has a **name** (`@name`, set at construction) that is the unique per-agent key, and a **type** (from the class) that identifies the monitor class. Multiple instances of the same type can coexist under different names (e.g. two `:shell` monitors named `:disk_check` and `:mem_check`).
+
+Type inference: when a monitor config hash has no `:type` key, the name is used to look up the class. So `github: { ... }` infers type `:github`.
+
+`dispatch(event)` stamps both `monitor_type` and `monitor_name` on the event before passing it to the injector. Events are enqueued on the agent-side `InjectionQueue` via `Buffer::Client`; pending event management is handled agent-side with TTL and priority semantics. Monitors can include `injection_priority`, `injection_ttl`, and `injection_supersede_key` in the event hash to control queue behavior per-event (see Injector docs).
+
+Optionally define a nested `Probe` class (see below) for auto-detection of monitor config from the local environment. `Monitor.register` automatically picks up `MyMonitor::Probe` if it exists.
+
+### `Superkick::Spawner` (`spawner.rb`)
+Extends `Poller` for server-level spawners that create new agents in response to external events. Separate registry from Monitor (they don't collide). Subclasses implement:
+- `self.type` → Symbol (unique, e.g. `:shortcut`)
+- `self.required_config` → Array of required config key Symbols
+- `self.agent_id(event)` → deterministic agent ID from event data (e.g. `"shortcut-story-42"`)
+- `self.spawn_templates_dir` → path to spawn Liquid templates (or nil)
+- `tick` → called each `poll_interval`; call `dispatch(event_hash)` to emit
+
+`dispatch(event)` stamps `monitor_type`, `monitor_name`, and `agent_id` (via `self.class.agent_id(event)`) on the event before passing it to the `Spawn::Handler`.
+
+Dedup is handled by `AgentStore` — if an agent with the same ID already exists, the spawn is skipped.
+
+**`_spawn_monitors` mechanism:** Spawners can include a `_spawn_monitors` key in the dispatched event hash. This is a Hash of `{ monitor_name: config_hash }` that `Spawn::AgentSpawner` auto-attaches to the spawned agent at startup, alongside any monitors from the spawner config or probe detection. The key is listed in `Spawn::AgentSpawner::INTERNAL_EVENT_KEYS` and is stripped from the event before template rendering. This mechanism allows spawners to dynamically attach monitors based on event context — for example, the Slack spawner uses it to attach a `:slack_thread` monitor, and `Spawn::Handler#enrich_for_team` uses it to attach the `:team_log` monitor to team leads.
+
+**`_spawn_notifiers` mechanism:** Parallel to `_spawn_monitors`, spawners can include a `_spawn_notifiers` key in the dispatched event hash. This is a Hash of `{ notifier_name: config_hash }` that `Spawn::AgentSpawner` stores on the agent's `notifiers` hash and registers with the `NotificationDispatcher` via `register_agent_notifiers(agent_id)`. Per-agent notifiers fire alongside global notifiers for that agent's events only, and are cleaned up when the agent finishes. The key is listed in `Spawn::AgentSpawner::INTERNAL_EVENT_KEYS` and is stripped from the event before template rendering. `attach_spawn_notifiers` is called after `attach_spawn_monitors` in the spawn flow. The Slack spawner uses this to attach a per-agent Slack notifier with a pre-seeded `thread_ts` for thread correlation. Workflow children inherit per-agent notifiers from their parent via `WorkflowExecutor`.
+
+**`working_dir` on spawned agents:** After spawning an agent, `Spawn::AgentSpawner` calls `agent.set_working_dir(working_dir)` to record the agent's working directory on the `Agent` object. This is the directory passed to the agent process (e.g. a VCS-acquired worktree). The Supervisor uses the agent's stored environment snapshot when starting monitor threads to call `MonitorClass.resolve_config` for config inference.
+
+### `Superkick::Goal` (`goal.rb`)
+Base class for spawned agent goal checks. A goal defines what "finished" means for a spawned agent. The Supervisor runs a periodic check thread per spawned agent; on each tick it calls `check` and acts on the result.
+
+Subclass contract:
+- `self.type` → unique Symbol (e.g. `:command`, `:agent_exit`, `:agent_signal`)
+- `self.description` → human-readable description (for `superkick_discover_goals` MCP tool)
+- `self.required_config` → Array of required config key Symbols (default `[]`)
+- `check` → one of `STATUSES`
+- `teardown` → optional cleanup (default no-op)
+
+Status vocabulary:
+- `:pending` — not started / waiting (non-terminal, default)
+- `:in_progress` — actively working (non-terminal, stored for observability)
+- `:errored` — potentially recoverable issue (non-terminal, stored)
+- `:completed` — succeeded (terminal → terminates agent)
+- `:failed` — irrecoverable (terminal → terminates agent)
+- `:timed_out` — max_duration exceeded (terminal, set by Supervisor)
+
+`TERMINAL_STATUSES = %i[completed failed timed_out]` — the Supervisor terminates the agent when `check` returns one of these. Non-terminal statuses (`:in_progress`, `:errored`) are stored on the agent for observability but the goal checker keeps running.
+
+Registry follows the standard pattern:
+```ruby
+Superkick::Goal.register(MyGoal)
+Superkick::Goal.lookup(:my_goal)
+Superkick::Goal.registered
+Superkick::Goal.build(goal_config, agent_id:)  # → instance from :type key
+```
+
+Built-in goals:
+- **`AgentExit`** (`:agent_exit`) — signals when the AI CLI process exits. The Supervisor calls `signal!(status)` when the agent process ends (clean exit → `:completed`, non-zero → `:failed`). Passive — doesn't actively poll.
+- **`Command`** (`:command`) — runs a shell command periodically; exit code determines status. Config: `run` (required), `timeout` (default 30). Passes `SUPERKICK_AGENT_ID` and `SUPERKICK_GOAL_*` env vars (use `exit $SUPERKICK_GOAL_IN_PROGRESS` instead of magic numbers). Exit code convention: `0` → `:completed`, `1` → `:pending`, `2` → `:in_progress`, `3` → `:errored`, `4` → `:failed`, `5-125` → `:errored` (reserved), `126+` → `:failed` (shell/OS errors).
+- **`AgentSignal`** (`:agent_signal`) — the **default goal type**. Signals when the AI CLI calls the `superkick_signal_goal` MCP tool. Purely reactive; the signal arrives via IPC → `Supervisor#signal_goal` → `goal.signal!(status)`. Accepts any status (`:completed`, `:failed`, `:errored`, `:in_progress`). Spawners do not need to explicitly specify this goal type — it is used automatically when no `goal:` config is provided.
+- **`Integrations::GitHub::PrMergedGoal`** (`:github_pr_merged`) — polls GitHub via Octokit to check whether a PR has been merged. All config is optional: `repo` and `branch` are auto-detected from the git working directory (the `Spawn::AgentSpawner` injects `working_dir` into the goal config at spawn time). Once a PR is found via branch search, its number is cached for efficient direct lookups. Status mapping: merged → `:completed`, closed without merge → `:failed`, open → `:in_progress`, no PR found → `:pending`, API error → `:errored`. Token falls back to `GITHUB_TOKEN` env var.
+- **`Integrations::GitHub::IssueResolvedGoal`** (`:github_issue_resolved`) — polls GitHub via Octokit to check whether an issue has been closed. Any close reason (completed or not_planned) counts as success. Config: `issue` (required, `IssueDrop` injected from spawn event context by `Spawn::AgentSpawner` — provides `.number`), `repo` (optional, auto-detected from git remote), `token` (optional, falls back to `GITHUB_TOKEN`). Status mapping: closed → `:completed`, open → `:in_progress`, missing config → `:pending`, API error → `:errored`.
+- **`Integrations::Datadog::AlertResolvedGoal`** (`:datadog_alert_resolved`) — polls the Datadog Monitors API to check whether a monitor has recovered (returned to OK status). Config: `monitor_id` (injected from spawn event context), `site` (optional, default `"datadoghq.com"`), `api_key` (optional, falls back to `DD_API_KEY`), `application_key` (optional, falls back to `DD_APP_KEY`). Status mapping: OK → `:completed`, Alert/Warn → `:in_progress`, No Data → `:pending`, API error → `:errored`.
+
+Configuration (in spawner config):
+```yaml
+spawners:
+  my_spawner:
+    goal:
+      type: agent_signal      # this is the default, can be omitted
+    max_duration: 3600        # hard timeout in seconds
+    cooldown: 300             # minimum seconds between spawns
+    approval_required: true   # require human approval before spawning
+    stall_threshold: 300      # seconds idle before agent_stalled notification
+    repository: api           # auto-acquire working copy from repositories config
+    branch_template: "fix/{{ issue.number }}"  # Liquid template for branch name
+    base_branch: main         # branch to base the working copy on
+    budget:                   # cost budget enforcement
+      max_cost_usd: 50.0     # aggregate cap across all agents from this spawner
+      window_hours: 24        # time window for spawner aggregate
+      warning_threshold_percentage: 80  # fires warning at this % of max
+      enforce: notify         # "notify" (default) or "hard" (terminates agent)
+      per_agent:
+        max_cost_usd: 5.0    # per-agent cost cap
+        warning_threshold_percentage: 80
+```
+
+The Supervisor runs a goal checker thread per spawned agent. On each tick it checks `max_duration` (terminates if exceeded, sets status to `:timed_out`) and `goal.check`. Terminal statuses (`:completed`, `:failed`) trigger agent termination. Non-terminal statuses (`:in_progress`, `:errored`) are stored on the agent but the checker keeps running. The check interval defaults to `poll_interval` but can be overridden with `check_interval` in the goal config.
+
+When `approval_required: true` is set, spawn events are held in the `Spawn::ApprovalStore` instead of spawning immediately. An `agent_pending_approval` notification is fired. The user approves via `superkick approve <id>` or rejects via `superkick reject <id> [--reason REASON]`. Rejections are persistent (within a server lifetime) — the spawner won't re-dispatch a rejected agent ID until the rejection is cleared.
+
+### `Superkick::VersionControl` (`version_control.rb`)
+Base class for version control adapters. A version control adapter knows how to acquire a working copy of a repository (via worktree, clone, etc.) and tear it down when no longer needed. Used by `Spawn::AgentSpawner` when a spawner config specifies `repository:` to automatically set up a working copy for a spawned agent.
+
+Subclasses implement:
+- `self.type` → unique Symbol (e.g. `:git`)
+- `acquire(source:, destination:, branch:, base_branch:)` → create a working copy at `destination` from `source` (a `Repository` object). `branch` is the branch name to create/checkout; `base_branch` is the branch to base it on.
+- `teardown(destination:)` → remove the working copy at `destination`
+
+Registry follows the standard pattern:
+```ruby
+Superkick::VersionControl.register(MyAdapter)
+Superkick::VersionControl.lookup(:my_vcs)
+Superkick::VersionControl.registered
+Superkick::VersionControl.for_repository(repository)  # → instance for the repository's VCS type
+Superkick::VersionControl.detect_from_path(path:)     # → convenience alias for VersionControl::Probe.detect_from_path
+```
+
+Auto-registration: `VersionControl.register(adapter)` automatically registers `adapter::Probe` if the adapter defines a nested `Probe` class (same pattern as `Monitor.register`).
+
+### `Superkick::VersionControl::Probe` (nested in `version_control.rb`)
+Abstract base class for VCS detection probes. Each VCS adapter can define a nested `Probe` class that detects its presence by inspecting a local directory path directly.
+
+Subclasses implement:
+- `self.type` → Symbol (e.g. `:git`)
+- `self.detect_at(path:)` → `{ type: :git }` or `nil`
+
+Key class methods:
+- `VersionControl::Probe.detect_from_path(path:)` — runs all registered probes against a local directory path, returns first match (e.g. `{ type: :git }`) or `nil`
+- `VersionControl::Probe.register(probe_class)` / `VersionControl::Probe.registered` — standard registry pattern
+
+`VersionControl.detect_from_path(path:)` is a convenience alias for `VersionControl::Probe.detect_from_path(path:)`. Used by `Local::RepositorySource` to detect VCS type without hardcoding specific VCS checks. `Repository` is a pure value object and does not perform VCS detection — the source that constructs it is responsible for detecting and passing the `version_control:` value.
+
+Built-in adapters:
+- **`Superkick::Integrations::Git::VersionControl`** (`:git`) — uses `git worktree add` when the repository has a local path, falls back to `git clone` when URL-only. Teardown removes the worktree (or deletes the clone directory). Located at `lib/superkick/integrations/git/version_control.rb`. Defines a nested **`VersionControl::Probe`** that checks for `.git` (directory or file for worktrees) via `File.exist?` and returns `{ type: :git }` or `nil`.
+
+The `Spawn::AgentSpawner` integration:
+1. Spawner config specifies `repository: api` (name from `repositories:` config)
+2. `Spawn::AgentSpawner` looks up the `Repository` from `RepositorySource`
+3. Creates a `VersionControl` adapter via `VersionControl.for_repository(repository)`
+4. Calls `acquire(source:, destination:, branch:, base_branch:)` where destination is `workspaces_dir/<agent_id>`
+5. VCS state (adapter + destination) is tracked per agent and cleaned up when the agent ends
+6. `Spawn::WorkflowExecutor` transfers VCS state alongside pipeline state to child agents
+
+### `Superkick::RepositorySource` (`repository_source.rb`)
+Abstract base class for repository sources used by team planning agents. Provides the source pattern (register/lookup/build) and shared query methods.
+
+Subclass contract:
+- `self.type` → unique Symbol (e.g. `:local`, `:git`, `:github_organization`)
+- `repositories` → Hash of `{ name_sym => Repository }`
+- Inherits: `find_by_name(n)`, `to_prompt_context`, `empty?`, `size`
+- `self.setup_label` → (optional) short name for the `superkick setup` wizard
+- `self.setup_config` → (optional) YAML snippet string for config generation
+
+`RepositorySource.build(config)` accepts a Hash where each key is a user-chosen name and each value is either:
+- **No `:type` key, has `:path` key** → a `Local::RepositorySource` with `depth: 0` (single repo)
+- **No `:type` key, no `:path` key** → silently skipped
+- **Has `:type` key** → a typed source config, built as its own typed source
+
+When the result is a single source, it's returned directly. When there are multiple, they're composited via `CompositeRepositorySource`. Empty config returns an empty `Local::RepositorySource`.
+
+Built-in implementations:
+
+**`Local::RepositorySource`** (`:local`) — filesystem-based repository source. Auto-detects `version_control` via `VersionControl::Probe.detect_from_path`. Discovers context documents via `Dir.glob` against configured patterns. Behavior depends on `depth:`:
+- `depth: 0` (default) — treats `path:` as a single repository. Accepts `name:` override (defaults to directory basename).
+- `depth: 1+` — scans subdirectories of `path:` for repositories.
+
+Located at `lib/superkick/local/repository_source.rb`.
+```yaml
+# Single repository (depth: 0 is default)
+repositories:
+  api:
+    path: ~/projects/api
+    dependencies: [shared]
+  web:
+    path: ~/projects/web
+    dependencies: [api]
+
+# Directory scan
+repositories:
+  local:
+    type: local
+    path: ~/projects
+    context_documents: [readme, claude_md]  # documents to discover (merged with global context_documents)
+    depth: 1                 # scan subdirectories
+    exclude: [node_modules]  # directory names to skip
+```
+
+**`Integrations::Git::RepositorySource`** (`:git`) — single-repo source for URL-based git repositories. Config: `url:` (required), `name:` (optional override, defaults to repo name parsed from URL). Located at `lib/superkick/integrations/git/repository_source.rb`.
+```yaml
+repositories:
+  upstream:
+    type: git
+    url: https://github.com/org/repo.git
+    name: custom_name        # optional — overrides the default name parsed from URL
+```
+
+**`Integrations::GitHub::OrganizationRepositorySource`** (`:github_organization`) — fetches repositories from a GitHub organization or user account via the API. All metadata (descriptions, topics, clone URLs) is fetched using the GitHub API token — no SSH keys needed. Context documents are fetched via the GitHub API: `:readme` uses Octokit's `readme` endpoint; other documents are fetched via the `contents` API (direct path) or `tree` + `contents` (glob patterns). Located at `lib/superkick/integrations/github/repository_source.rb`.
+```yaml
+repositories:
+  company:
+    type: github_organization
+    organization: my-company
+    token: <%= env("GITHUB_TOKEN") %>
+    include_archived: false    # include archived repositories (default false)
+    include_forks: false       # include forked repositories (default false)
+    topic_filter: [production] # only repositories with ALL listed topics
+    exclude: [legacy-app]      # repository names to exclude
+    context_documents: [readme, claude_md]  # documents to fetch (merged with global context_documents)
+    visibility: all            # public, private, or all (default all)
+```
+
+**`CompositeRepositorySource`** (`:composite`) — unions multiple sources. Built automatically when `repositories:` contains multiple sources. First-found precedence on name collisions. Exposes `children` for introspection.
+```yaml
+# Mix of local repos, git URL, directory scan, and GitHub org:
+repositories:
+  api:
+    path: ~/projects/api
+  upstream:
+    type: git
+    url: https://github.com/org/upstream.git
+  company:
+    type: github_organization
+    organization: my-company
+    token: <%= env("GITHUB_TOKEN") %>
+  local:
+    type: local
+    path: ~/projects/local
+    depth: 1
+```
+
+`Superkick::Repository` — pure value object for a single repository. Fields: `name` (Symbol), `path`, `url`, `dependencies` (Array of Strings), `context_documents` (Hash of `{ name_sym => content_string }`, default `{}`), `version_control` (Symbol or nil, e.g. `:git`). `Repository` does not perform filesystem access or VCS detection — the source that constructs it (e.g. `Local::RepositorySource`, `Integrations::Git::RepositorySource`) is responsible for detecting and passing the `version_control:` value.
+
+Convenience accessors for the `:readme` document:
+- `readme_content` → `context_documents[:readme]`
+- `readme_content=` → sets `context_documents[:readme]`
+
+Additional methods:
+- `set_context_document(name, content)` — sets a named document in `context_documents`
+- `to_h` — includes a `context_documents` key (array of document names) when documents are present
+
+`CONTEXT_DOCUMENT_PATTERNS` constant maps well-known document names to glob patterns used for auto-discovery:
+- `:readme` → `"README*"`, `:claude_md` → `"CLAUDE.md"`, `:agents_md` → `"AGENTS.md"`, `:contributing` → `"CONTRIBUTING*"`, `:conventions` → `"CONVENTIONS*"`, `:cursorrules` → `".cursorrules"`
+
+### `Superkick::Monitor::Probe` (nested in `monitor.rb`)
+Abstract base class for server-side environment probes. Probes run on the server using an environment snapshot collected from the agent via `EnvironmentExecutor`, rather than having direct filesystem access. Subclasses implement:
+- `self.type` → Symbol
+- `self.environment_actions` → Array of action hashes describing what environment data the probe needs (e.g. `[{ action: :git_branch }, { action: :git_remotes }]`)
+- `self.detect(environment:)` → `{}` or `{ monitor_name: { type: "…", config… } }` hash (symbol keys)
+
+The returned hash keys are monitor **names** as Symbols (unique per agent). Each config hash should include a `:type` key identifying the monitor class. When the name matches a registered monitor type, `:type` may be omitted.
+
+Key class methods:
+- `Monitor::Probe.detect_all(environment:)` (also accessible as `Monitor.detect_all(environment:)`) — runs all registered probes against an environment snapshot to auto-configure monitors. Called server-side during `register_environment` processing, where the returned hash is merged with YAML-configured monitors (YAML is the base, probes overlay).
+- `Monitor::Probe.all_environment_actions` (also accessible as `Monitor.all_environment_actions`) — collects and deduplicates action hashes from all registered probes. Called during `register` to build the `environment_request` response.
+
+Probes are defined as nested classes inside their monitor (e.g. `Integrations::GitHub::Monitor::Probe < Monitor::Probe`) and are automatically registered when the monitor is registered.
+
+### `Superkick::Agent::Runtime` (`agent/runtime.rb`)
+Abstract base class for agent process runtimes. A runtime knows how to provision a compute environment for an agent process, terminate it, and check whether it's still alive. The `Spawn::AgentSpawner` delegates to a `Runtime` instead of calling `Process.spawn` directly.
+
+Subclass contract:
+- `self.type` → unique Symbol (e.g. `:local`, `:docker`)
+- `provision(agent_id:, config:)` → Handle (opaque lifecycle handle)
+- `terminate(handle:)` → nil
+- `alive?(handle:)` → Boolean
+- `metadata(handle:)` → Hash (optional, default `{}`)
+
+The `config` Hash passed to `provision` contains: `{ env: Hash, command: Array, working_dir: String }`.
+
+Each runtime defines its own Handle as a `Data.define` with the fields it needs. Handles are ephemeral — they are stored in-memory on `Spawn::AgentSpawner` and do not survive server restarts.
+
+Registry follows the standard pattern:
+```ruby
+Superkick::Agent::Runtime.register(MyRuntime)
+Superkick::Agent::Runtime.lookup(:my_runtime)
+Superkick::Agent::Runtime.registered
+```
+
+Built-in runtimes:
+- **`Agent::Runtime::Local`** (`:local`) — spawns agent processes on the same machine via `Process.spawn`. Sends SIGTERM on terminate, SIGKILL after 10 seconds if still alive. Uses `Process.kill(0, pid)` for liveness checks. `Handle = Data.define(:pid)`. This is the default runtime.
+- **`Integrations::Docker::Runtime`** (`:docker`) — provisions agents in Docker containers via the Docker Engine API. Lives in `integrations/docker/`. Supports Unix socket and TCP+TLS connections. Image pulling follows a configurable policy (`:always`, `:missing`, `:never`). Private registry auth via Base64-encoded credentials. `Handle = Data.define(:container_id, :container_name)`. Config: `image` (required), `host`, `tls`, `pull_policy`, `registry`, `memory`, `cpu`, `network`, `stop_timeout`, `auto_remove`, `env`, `volumes`, `labels`, `privileged`, `cap_add`, `security_opt`, `container_runtime`.
+
+### `Superkick::Integrations::Docker::Runtime` (`integrations/docker/runtime.rb`)
+Provisions spawned agents in Docker containers via the Docker Engine API. Containers are created with the agent's environment, command, and working directory, plus optional resource limits, networking, and volume mounts. Uses `Integrations::Docker::Client` for all API communication. Lives in `integrations/docker/` to signal that it follows the standard `Agent::Runtime` extension point and can be replicated by third-party gems.
+
+Constructor: `initialize(image:, host: "unix:///var/run/docker.sock", tls: nil, pull_policy: :missing, registry: nil, memory: nil, cpu: nil, network: nil, stop_timeout: 30, auto_remove: true, env: nil, volumes: nil, labels: nil, privileged: false, cap_add: nil, security_opt: nil, container_runtime: nil, server: {}, connection: nil)`. The `connection:` parameter accepts a pre-built Faraday connection for test injection (passed through to `Integrations::Docker::Client`).
+
+**Local connectivity auto-injection:** When the `server:` context has `type: :local`, the runtime automatically adds a bind mount for `{base_dir}/run` → `/superkick/run` and sets `SUPERKICK_DIR=/superkick` in the container environment. This allows containerized agents to communicate with the local server via Unix sockets without manual configuration. `Configuration#build_agent_runtime` injects the `server:` context automatically for all runtimes. User-configured `SUPERKICK_DIR` env values take precedence over the auto-injected default.
+
+Key methods:
+- `provision(agent_id:, config:)` — pulls the image (per `pull_policy`), creates and starts a container, returns a `Handle`
+- `terminate(handle:)` — stops the container (with `stop_timeout`) and removes it
+- `alive?(handle:)` — inspects the container and checks if it is running
+- `metadata(handle:)` — returns `{ container_id:, container_name: }`
+
+`Handle = Data.define(:container_id, :container_name)`.
+
+### `Superkick::Integrations::Docker::Client` (`integrations/docker/client.rb`)
+Faraday-based client for the Docker Engine API. Supports two connection modes: Unix socket (via a custom `UnixSocketAdapter` Faraday adapter) and TCP+TLS (standard Faraday with optional TLS client certificates). Accepts `connection:` for test injection.
+
+Constructor: `initialize(host: nil, tls: nil, connection: nil)`. When no `host:` is given, defaults to `unix:///var/run/docker.sock`. When `host:` starts with `unix://`, uses the `UnixSocketAdapter`. Otherwise, uses standard Faraday with optional TLS configuration from the `tls:` hash (`ca`, `cert`, `key` paths).
+
+Key methods:
+- `create_container(name:, body:)` — `POST /containers/create`
+- `start_container(id)` — `POST /containers/{id}/start`
+- `stop_container(id, timeout:)` — `POST /containers/{id}/stop`
+- `remove_container(id, force:)` — `DELETE /containers/{id}`
+- `inspect_container(id)` — `GET /containers/{id}/json`
+- `pull_image(image, tag:, auth:)` — `POST /images/create`
+- `inspect_image(image_ref)` — `GET /images/{image_ref}/json`
+
+Configuration (in `config.yml`):
+```yaml
+runtime:
+  type: local    # default, can be omitted
+```
+
+### `Superkick::Supervisor` (`supervisor.rb`)
+Server-side supervisor. When an agent registers, it starts one thread per monitor. Before constructing each monitor instance, `start_agent_monitor` calls `MonitorClass.resolve_config(config, environment: agent.environment)` when the agent has an environment snapshot, allowing monitors to fill in missing config from the environment data. Threads run `monitor.run` (the blocking loop). Also manages spawner threads (server-level pollers), goal checker threads (per spawned agent), and cost poller threads (per spawned agent with budget config). On agent unregister or server shutdown, threads are killed. Has an `agent_spawner=` setter that also wires up the `Spawn::WorkflowExecutor` (constructed with the spawner, store, and notification dispatcher).
+
+The goal checker fires lifecycle notifications when spawned agents reach terminal states:
+- `:completed` → `agent_completed` notification
+- `:failed` → `agent_failed` notification
+- `:timed_out` → `agent_timed_out` notification
+- `:errored` → `agent_blocked` notification (non-terminal, checker continues)
+
+The Supervisor also supports claim/unclaim for spawned agents:
+- `pause_goal_checker(agent_id)` — pauses the goal checker thread (skips checks while paused). Max duration is frozen.
+- `resume_goal_checker(agent_id)` — resumes the goal checker. Max duration budget is preserved from when it was paused.
+- `goal_paused?(agent_id)` — returns whether the goal checker is paused.
+
+Stall detection is configured per-spawner with `stall_threshold:` (seconds). When a spawned agent is idle past this threshold, an `agent_stalled` lifecycle notification fires (once, until the agent becomes active again).
+
+Cost poller management:
+- `start_cost_poller(agent_id:, spawner_config:)` — starts a `CostPoller` thread for the agent
+- `stop_cost_poller(agent_id:)` — kills the cost poller thread (also called automatically by `stop_goal_checker`)
+
+### `Superkick::Connection` (`connection.rb`)
+Newline-delimited JSON framing over raw sockets. Wraps a socket and provides `send_message`, `reply`, `error`, `receive_message`, and `close`. Used by the control plane (`Control::Client`, `Control::Server`) and the data plane (`Buffer::Server`, `Buffer::Client`, etc.). A shared primitive, not specific to control messages.
+
+### `Superkick::Control::Client` (`control/client.rb`)
+Default Unix socket implementation of the control client. All call sites (CLI commands, MCP server, PtyProxy, Attach::Server) use `Control.client_from` to construct the appropriate instance.
+
+The `Control` module extends `ClientRegistry` and provides `Control.client_from(config:, connection:)` — returns a `Control::Client` (Unix socket) for `:local` server type, or the registered hosted client for `:hosted`. The `connection:` parameter is for test injection of a Faraday connection (hosted mode only). Hosted subclasses register via `Control.register_client(:hosted, klass)`.
+
+The base class is the Unix socket implementation. Each `request` opens a fresh `UNIXSocket`, sends one JSON message via `Connection`, reads one response, and closes. When no `socket_path:` is given, uses `Superkick.config.socket_path`.
+
+Defines two shared exception classes:
+- `Control::Client::ServerUnavailable` — raised when the server is unreachable.
+- `Control::Client::AuthenticationError` — subclass of `ServerUnavailable`, raised by the hosted client when the server rejects the API key (HTTP 401).
+
+Key methods:
+- `request(command, **params)` — send a command, return a `Control::Reply`
+- `alive?` — check if the server is reachable
+- `close` — close the underlying connection
+
+Raises `Control::Client::ServerUnavailable` when the socket is missing or the server closes without responding.
+
+### `Superkick::Hosted::Control::Client` (`hosted/control/client.rb`)
+HTTPS subclass of `Control::Client`. All control commands go through `POST /api/v1/control` with the command name in the JSON body. Uses Faraday for HTTP with built-in middleware: `f.request :authorization` for Bearer token auth, `f.request :json` for automatic JSON serialization, and `f.response :json` for automatic JSON deserialization with `symbolize_names: true`. Maps HTTP errors to `ServerUnavailable` (connection/timeout errors, non-200 status) or `AuthenticationError` (401). Accepts an optional `connection:` constructor parameter for test injection. Self-registers as the `:hosted` client on `Control`.
+
+### `Superkick::Control::Server` (`control/server.rb`)
+Unix socket server — the control plane's main endpoint. One thread per connection (connections are short-lived request/response). Commands are dispatched dynamically to `cmd_<command>` private methods. Uses `Connection` for JSON message framing.
+
+Key commands related to the environment-based registration flow:
+- `register` — registers a new agent (no monitors). Returns `environment_request` containing action hashes collected from all registered monitor probes via `Monitor.all_environment_actions`.
+- `register_environment` — receives an environment snapshot from the agent, runs server-side probes (`Monitor.detect_all(environment:)`), merges with YAML-configured monitors, stores the environment on the agent, and starts monitor threads.
+- `list_agents` — returns all agents. Accepts optional `team_id:` (filter by team) and `spawned_only:` (only spawned agents) parameters for server-side filtering.
+- `list_teams` — returns unique teams with summary metadata (`team_id`, `agent_count`, `lead_agent_id`).
+- `team_status` — accepts `team_id:` directly (preferred) or `agent_id:` (legacy, derives team from agent).
+- `discover_monitors` — returns available monitor types, metadata, and probe-detected configs from the agent's stored environment snapshot.
+- `discover_goals` — returns available goal types.
+- `discover_notifiers` — returns available notifier types.
+
+### `Superkick::Control::Reply` (`control/reply.rb`)
+Wraps a parsed control response hash. Provides `success?`, `error?`, `error_message`, `[]`, and `payload` methods. Returned by `Control::Client#request`.
+
+### `Superkick::McpServer` (`mcp_server.rb`)
+**Local mode only.** Runs as `superkick mcp start` — a stdio MCP server the AI CLI connects to. Each tool proxies to the server via `Control::Client`. In hosted mode, `superkick mcp start` launches `Hosted::McpProxy` instead (see above). Reads `SUPERKICK_AGENT_ID` from the environment at startup (set by `PtyProxy` when spawning the AI CLI) — all tools that need the agent's identity use this automatically rather than requiring the AI to pass it as a parameter. Aborts if the env var is missing.
+
+Core tools: `superkick_discover_monitors` (thin proxy to the control server — no local registry iteration or probe execution), `superkick_discover_goals` (thin proxy to the control server), `superkick_add_monitor`, `superkick_remove_monitor`, `superkick_signal_goal`, `superkick_report_cost`, `superkick_status`. Notifier tools: `superkick_discover_notifiers` (thin proxy to the control server), `superkick_add_notifier`, `superkick_remove_notifier`. Team tools: `superkick_spawn_worker` (with optional `role`, `monitors`, and `notifiers`), `superkick_team_status`, `superkick_post_update`, `superkick_list_teammates`, `superkick_discover_repositories`, `superkick_publish_artifact`, `superkick_read_artifact`, `superkick_list_artifacts`. None of these tools require `agent_id` as a parameter — it is always read from the environment.
+
+The `superkick_signal_goal` tool lets the AI CLI signal goal status (`completed`, `failed`, `errored`, `in_progress`) for spawned agents, with an optional `summary` parameter that provides a brief description of the outcome (forwarded as `parent_goal_summary` in workflow chains). The `superkick_post_update` tool replaces the former `superkick_team_update` and `superkick_send_message` tools with a unified interface. Params: `message` (required), `kind` (optional — one of `status`, `decision`, `blocker`, `progress`, `completed`, `failed`), `target_agent_id` (optional — when present, sends a directed message to a specific teammate instead of a broadcast update). The `superkick_discover_repositories` tool returns structured repository data (name, dependencies, path, URL) from the configured repository sources. The `superkick_discover_notifiers` tool returns a list of available notifier types the agent can use. The `superkick_add_notifier` tool adds a per-agent notifier by name, type, and optional config. The `superkick_remove_notifier` tool removes a per-agent notifier by name. Both add/remove tools respect privileged notifier restrictions. The `superkick_spawn_worker` tool accepts optional `monitors` (Hash of name → config) and `notifiers` (Hash of name → config) to pre-configure workers at spawn time. The `team_log` monitor is always auto-attached to workers; explicit monitors merge on top. The artifact tools allow agents to publish, read, and list persistent team artifacts stored at `~/.superkick/teams/<team_id>/artifacts/`. Agent registration, unregistration, and monitor restarts are handled internally by the PTY proxy and server — they are not exposed as MCP tools.
+
+### `Superkick::Setup` (`setup.rb`)
+Generates a well-documented `config.yml` from user selections. Each integration provides a `self.setup_config` class method (raw YAML string with comments) and a `self.setup_label` method (short name for the setup menu). The setup command concatenates selected snippets into a final config.
+
+Key methods:
+- `detect_drivers` — returns registered drivers with installation status
+- `available_monitors` / `available_spawners` / `available_notifiers` / `available_repository_sources` — returns integrations with `setup_label`
+- `generate_config(driver:, monitors:, spawners:, notifiers:, repository_sources:)` — assembles the config.yml string
+
+### `Superkick::CLI` (`cli.rb`)
+Thor-based CLI organized into subcommands. Global option `--dir` / `-C` overrides `SUPERKICK_DIR`. Each subcommand has a `default_command` so bare invocation works (e.g. `superkick server` runs `superkick server start`).
+
+Subcommands:
+- **`superkick server`** — `start` (default), `stop`, `status`, `log`
+- **`superkick agent`** — `start` (default, wraps AI CLI in PTY; `--team TEAM_ID`, `--role LABEL`, `--no-feed`; hidden flags: `--agent-id ID`, `--headless` — used by `Spawn::AgentSpawner`), `list`, `log <id>`, `stop <id>`, `attach <id>` (`-i` for RW, `-f` / `--force` for force-takeover), `claim <id>`, `unclaim <id>`, `cost [id]`, `report-cost <id>` (`--tokens_in`, `--tokens_out`, `--cost_usd`), `add-monitor <id> <name>` (`--type`, `--config`), `remove-monitor <id> <name>`, `add-notifier <id> <name>` (`--type`, `--config`), `remove-notifier <id> <name>`
+- **`superkick monitor`** — `list` (default), `install-templates`
+- **`superkick spawner`** — `list` (default), `start <name>`, `stop <name>`, `install-templates`
+- **`superkick team`** — `list` (default), `status <id>`, `watch <id>`, `stop <id>`, `artifacts <id>` (`--author`, `--json`), `artifact <id> <author> <name>` (`--json`), `message <id> <text>` (broadcast to all agents), `spawn-worker <team_id>` (`--repository`, `--task`, `--role`, `--goal-type`, `--depends-on`, `--monitors`, `--notifiers`)
+- **`superkick mcp`** — `start` (default, stdio MCP server), `configure`
+- **`superkick goal`** — `list` (default, discover goal types), `signal <agent_id> <status>` (`--summary`)
+- **`superkick notifier`** — `list` (default, discover notifier types)
+- **`superkick repository`** — `list` (default, list configured repositories; `--json`)
+- **`superkick setup`** — `start` (default, interactive first-time setup; `--driver`, `--force`, `--skip-mcp`, `--skip-completions`)
+
+Top-level commands:
+- **`superkick approve <id>`** — approve a pending spawn
+- **`superkick reject <id>`** — reject a pending spawn (with optional `--reason`)
+- **`superkick reject --clear <id>`** — clear a rejection to allow re-dispatch
+- **`superkick reject --clear-all`** — clear all rejections
+- **`superkick approvals`** — list pending approvals (with `--rejections` flag for rejections)
+- **`superkick completion`** — `install` (default, prints shell completion script for `bash` or `zsh`). Hidden helper subcommands provide dynamic completions: `agents` (`--spawned`, `--team`), `team-ids`, `spawner-names`, `approval-ids`, `monitor-types`, `monitors-for <id>`, `notifier-types`, `notifiers-for <id>`, `goal-types`, `goal-statuses`, `driver-names`, `repository-names`, `artifact-authors <team>`, `artifact-names <team> <author>`. All helpers silently return nothing when the server is unavailable.
+
+## Plugin registries
+
+Nine independent registries, all using the same pattern:
+
+```ruby
+# Drivers
+Superkick::Driver.register(MyDriver)            # keyed by MyDriver.driver_name
+Superkick::Driver.lookup(:my_cli)               # → class
+Superkick::Driver.registered                    # → frozen hash of all registered classes
+
+# Monitors (+ their probes)
+Superkick::Monitor.register(MyMonitor)           # keyed by MyMonitor.type; auto-registers MyMonitor::Probe
+Superkick::Monitor::Probe.register(MyProbe)      # direct probe registration (rarely needed)
+
+# Look up
+Superkick::Monitor.lookup(:github)               # → class
+Superkick::Monitor.registered                    # → frozen hash of all registered monitor classes
+Superkick::Monitor::Probe.registered             # → frozen hash of all registered probe classes
+Superkick::Monitor.detect_all(environment: {})   # → merged config from all registered probes
+Superkick::Monitor.all_environment_actions       # → deduplicated actions from all registered probes
+
+# Notifiers
+Superkick::Notifier.register(MyNotifier)         # keyed by MyNotifier.type
+Superkick::Notifier.lookup(:my_notifier)         # → class
+Superkick::Notifier.registered                   # → frozen hash of all registered notifier classes
+
+# Spawners (server-level pollers that spawn agents)
+Superkick::Spawner.register(MySpawner)           # keyed by MySpawner.type
+Superkick::Spawner.lookup(:my_service)           # → class
+Superkick::Spawner.registered                    # → frozen hash of all registered classes
+
+# Version control adapters (VCS operations for spawned agent workspaces)
+Superkick::VersionControl.register(MyAdapter)             # keyed by MyAdapter.type; auto-registers MyAdapter::Probe
+Superkick::VersionControl::Probe.register(MyProbe)        # direct probe registration (rarely needed)
+Superkick::VersionControl.lookup(:my_vcs)                 # → class
+Superkick::VersionControl.registered                      # → frozen hash of all registered classes
+Superkick::VersionControl.for_repository(repository)      # → instance for the repository's VCS type
+Superkick::VersionControl::Probe.registered               # → frozen hash of all registered probe classes
+Superkick::VersionControl.detect_from_path(path: ".")     # → first matching probe result, or nil
+
+# Goals (spawned agent completion checks)
+Superkick::Goal.register(MyGoal)                     # keyed by MyGoal.type
+Superkick::Goal.lookup(:my_goal)                     # → class
+Superkick::Goal.registered                           # → frozen hash of all registered classes
+Superkick::Goal.build(goal_config, agent_id:)        # → instance from :type key
+
+# Repository sources (catalog of repositories for team planning)
+Superkick::RepositorySource.register(MySource)     # keyed by MySource.type
+Superkick::RepositorySource.lookup(:my_type)       # → class
+Superkick::RepositorySource.registered             # → frozen hash of all registered classes
+Superkick::RepositorySource.build(config)          # → partitions by :type presence, composites if needed
+
+# Agent runtimes (process management backends for spawned agents)
+Superkick::Agent::Runtime.register(MyRuntime)        # keyed by MyRuntime.type
+Superkick::Agent::Runtime.lookup(:my_runtime)        # → class
+Superkick::Agent::Runtime.registered                 # → frozen hash of all registered classes
+
+# Driver profile sources (named driver configurations for spawners)
+Superkick::Driver::ProfileSource.register(MySource)  # keyed by MySource.type
+Superkick::Driver::ProfileSource.lookup(:my_type)    # → class
+Superkick::Driver::ProfileSource.registered          # → frozen hash of all registered classes
+Superkick::Driver::ProfileSource.build(config)       # → StaticProfileSource from hash
+```
+
+A single `Monitor.register` call wires up the monitor and its probe (if one is defined as a nested `Probe` class). Similarly, a single `VersionControl.register` call wires up the adapter and its probe (if one is defined as a nested `Probe` class).
+
+**Important**: The monitor class registry is keyed by **type** (Symbol). The per-agent instance registry (`Agent#monitors`) is keyed by **name** (Symbol). Multiple instances of the same type can coexist under different names. The `:type` key in monitor config is reserved.
+
+### Registry test isolation (`Superkick::Registry`)
+
+All registry classes include the `Superkick::Registry` module (on their singleton class), which provides test isolation methods. These are used to snapshot and restore registries in tests, replacing ad-hoc `deregister`/`register` patterns.
+
+**Block-scoped** (preferred for focused tests):
+```ruby
+Superkick::Monitor.with_registry do
+  Superkick::Monitor.register(StubMonitor)
+  # StubMonitor visible here, cleaned up automatically
+end
+
+# Pre-seed with specific entries:
+Superkick::Goal.with_registry(stub: StubGoal) do
+  assert_equal StubGoal, Superkick::Goal.lookup(:stub)
+end
+```
+
+**Paired save/restore** (for Minitest `before`/`after` hooks):
+```ruby
+before do
+  @saved_registry = Superkick::Monitor.snapshot_registry
+  Superkick::Monitor.register(StubMonitor)
+end
+
+after do
+  Superkick::Monitor.restore_registry(@saved_registry)
+end
+```
+
+**Note**: Registry snapshot/restore replaces the `@registry` hash reference. This is NOT thread-safe across parallel tests when background threads perform registry lookups (e.g. Supervisor starting monitor threads). Tests that spawn background threads performing registry lookups should NOT use `parallelize_me!` even with snapshot/restore.
+
+## Configuration system
+
+Config is loaded from `~/.superkick/` (override via `SUPERKICK_DIR` env var) in two passes:
+
+1. `config.yml` — YAML processed through ERB first. Use `<%= env("VAR") %>` for secrets.
+2. `config.rb` — Ruby file, loaded after YAML, always wins.
+
+`Superkick.config` returns the `Superkick::Configuration` singleton. Key settings:
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `poll_interval` | `30` | Seconds between monitor ticks |
+| `idle_threshold` | `5.0` | Seconds CLI must be idle before injection |
+| `inject_clear_delay` | `0.15` | Sleep between PTY write chunks |
+| `rate_limit_backoff` | `60` | Backoff on API rate limit |
+| `error_backoff` | `10` | Backoff on general errors |
+| `log_level` | `:info` | Logger level |
+| `monitors` | `{}` | Named monitor configs from YAML `monitors:` section |
+| `privileged_types` | `[]` | Monitor types the AI cannot add/remove |
+| `notifications` | `[]` | Array of notifier configs from YAML `notifications:` section (defaults to terminal bell when empty) |
+| `notification_privileged_types` | `[]` | Notifier types the AI cannot add/remove (analogous to `privileged_types` for monitors) |
+| `attach_escape_key` | `"\x01"` (Ctrl-A) | Escape prefix byte for attach sessions. Configurable via `ctrl-a` through `ctrl-z` in YAML |
+| `attach_rw_idle_timeout` | `300` | Seconds of no input before an RW attach client is auto-demoted to read-only. Set to `nil` or `0` to disable |
+| `attach_replay_buffer_size` | `65_536` | Size in bytes of the output replay buffer for attach relay (used in hosted mode) |
+| `attach_max_connections` | `10` | Maximum number of concurrent user connections per attach relay (used in hosted mode) |
+| `budget` | `{}` | Global budget config hash (`max_cost_usd`, `window_hours`) |
+| `cost_poll_interval` | `nil` | CostPoller check frequency in seconds (nil = 300s default) |
+| `cost_stale_after` | `nil` | Seconds before cost data is considered stale (nil = 600s default) |
+| `repositories` | `{}` | Repository source config from YAML `repositories:` section |
+| `context_documents` | `[]` | Global list of context document names to discover (e.g. `[readme, claude_md]`). Merged with per-source `context_documents`. Resolved to glob patterns via `CONTEXT_DOCUMENT_PATTERNS` |
+| `driver_profiles` | `{}` | Named driver profile configs from YAML `drivers.profiles` section |
+| `server` | `{}` | Server connection config from YAML `server:` section (url, api_key) |
+| `runtime` | `{}` | Agent runtime config from YAML `runtime:` section (type, docker options) |
+| `session_recording_enabled` | `true` | Record timestamped sessions in asciicast v2 format |
+| `session_recording_max_size` | `104857600` | Max recording file size in bytes (100 MB) before rotation |
+
+### YAML `drivers:` section
+
+The `drivers:` section configures driver-specific options and named profiles:
+
+```yaml
+drivers:
+  # Per-driver-type options (used by interactive agents)
+  claude_code:
+    cli_command: /opt/bin/claude
+    config_dir: /custom/path/.claude
+
+  # Named profiles (used by spawners via profile: key)
+  profiles:
+    review:
+      type: claude_code
+      config_dir: ~/.superkick/driver-configs/review/.claude
+      env:
+        ANTHROPIC_API_KEY: <%= env("REVIEW_KEY") %>
+    worker:
+      type: claude_code
+      config_dir: ~/.superkick/driver-configs/worker/.claude
+      args: ["--verbose"]
+```
+
+Spawners reference profiles via `driver: { profile: :review }`. Inline overrides can be deep-merged on top of the profile:
+
+```yaml
+spawners:
+  my_spawner:
+    driver:
+      profile: review
+      env:
+        EXTRA_VAR: value    # merged on top of profile env
+```
+
+The `driver_profile_source` lazy accessor on Configuration builds a `Driver::ProfileSource` from the `driver_profiles` config, analogous to `repository_source`.
+
+### YAML `server:` section
+
+The `server:` section configures how the agent connects to the Superkick control server. When absent or empty, agents connect to the local Unix socket (default). When `url:` is set to an HTTPS endpoint, agents use the hosted transport instead.
+
+```yaml
+# Hosted mode
+server:
+  url: https://superkick.example.com
+  api_key: <%= env("SUPERKICK_API_KEY") %>
+```
+
+The `server_type` is derived automatically: `:local` when no `url` is configured, `:hosted` when a `url` is present.
+
+### YAML `session_recording:` section
+
+The `session_recording:` section configures timestamped session recording. When absent, session recording is enabled by default.
+
+```yaml
+session_recording:
+  enabled: true           # default: true
+  max_size: 104857600     # 100 MB default, rotate if exceeded
+```
+
+### YAML `runtime:` section
+
+The `runtime:` section configures how spawned agents are provisioned. When absent or empty, agents are spawned as local processes (default). Other runtime types (e.g. `docker`) provision agents in isolated compute environments.
+
+```yaml
+# Local mode (default, can be omitted)
+runtime:
+  type: local
+
+# Docker mode
+runtime:
+  type: docker
+  docker:
+    host: unix:///var/run/docker.sock
+    tls:
+      ca: /path/to/ca.pem
+      cert: /path/to/cert.pem
+      key: /path/to/key.pem
+    image: superkick/agent:latest
+    pull_policy: missing
+    registry:
+      username: <%= env("DOCKER_REGISTRY_USER") %>
+      password: <%= env("DOCKER_REGISTRY_PASSWORD") %>
+      server: ghcr.io
+    memory: 4G
+    cpu: 2
+    network: superkick-net
+    stop_timeout: 30
+    auto_remove: true
+    env:
+      GITHUB_TOKEN: <%= env("GITHUB_TOKEN") %>
+    volumes:
+      - /home/user/.ssh:/root/.ssh:ro
+      - /home/user/.gitconfig:/root/.gitconfig:ro
+    labels:
+      app: superkick
+      environment: production
+    privileged: false                    # run in privileged mode (for DinD)
+    cap_add:                             # Linux capabilities to add
+      - SYS_ADMIN
+    security_opt:                        # security options
+      - seccomp:unconfined
+    container_runtime: sysbox-runc       # OCI runtime (for unprivileged DinD)
+```
+
+The `agent_runtime` lazy accessor on Configuration builds the runtime instance from this config. The runtime type's nested config hash (e.g. `docker:` for `type: docker`) is passed as constructor kwargs via `klass.new(**runtime_config)`. A `server:` context hash is always injected, containing `{ type: :local, base_dir: "..." }` or `{ type: :hosted }` depending on `server_type`. Runtimes use this to set up server connectivity (e.g. Docker auto-mounts the `run/` directory when type is `:local`).
+
+### YAML `context_documents:` section
+
+The `context_documents:` section specifies which context documents should be discovered across all repository sources. Values are well-known document names from `Repository::CONTEXT_DOCUMENT_PATTERNS`. Per-source `context_documents` configs are merged with this global list.
+
+```yaml
+context_documents:
+  - readme
+  - claude_md
+  - agents_md
+  - contributing
+```
+
+Recognized names and their glob patterns: `readme` → `README*`, `claude_md` → `CLAUDE.md`, `agents_md` → `AGENTS.md`, `contributing` → `CONTRIBUTING*`, `conventions` → `CONVENTIONS*`, `cursorrules` → `.cursorrules`.
+
+`Configuration#resolved_context_document_patterns` resolves the `context_documents` config array into a `{ name_sym => glob_pattern }` hash by looking up each name in `Repository::CONTEXT_DOCUMENT_PATTERNS`. Repository sources merge this global hash with their own per-source `context_documents` list before running discovery.
+
+When present on a repository, each context document is rendered in `to_prompt_context` as `"Doc name (excerpt):"` with the first 30 lines.
+
+### YAML `monitors:` section
+
+Named monitor instances are configured under the `monitors:` key in `config.yml`. Each key is the monitor **name**; the config hash may include a `:type` key to specify the monitor class. When `:type` is omitted, the name is used as the type. After YAML loading, all keys are symbolized via `YAML.safe_load(…, symbolize_names: true)`.
+
+Use **snake_case** for monitor and spawner names so they work naturally as Ruby symbols (e.g. `:disk_check` not `:"disk-check"`). The shell probe auto-converts hyphens in filenames to underscores.
+
+```yaml
+monitors:
+  github:                              # name=github, type inferred as "github"
+    token: <%= env("GITHUB_TOKEN") %>
+  disk_check:                          # name=disk_check, type=shell
+    type: shell
+    command: ./scripts/check_disk.sh
+  mem_check:                           # name=mem_check, type=shell
+    type: shell
+    command: ./scripts/check_mem.sh
+    report_success: true
+```
+
+YAML-configured monitors serve as base defaults. At agent registration time, probe-detected monitors are merged on top (probes win on key conflict within a name).
+
+### Privileged monitors
+
+Privileged monitors cannot be added or removed by the AI coding agent via MCP tools (`superkick_add_monitor`, `superkick_remove_monitor`). They are also hidden from AI-facing responses (`list_monitors`, `list_agents`, `discover_monitors`).
+
+Two levels of protection:
+
+1. **By name** — set `privileged: true` on a monitor config:
+```yaml
+monitors:
+  github:
+    privileged: true
+    token: <%= env("GITHUB_TOKEN") %>
+```
+
+2. **By type** — use the `privileged_types` array under `monitors:` to protect all instances of a monitor type:
+```yaml
+monitors:
+  privileged_types:
+    - shell
+```
+
+Enforcement happens at the server's control layer (`Control::Server`). Registration and restart are not affected — those are internal operations.
+
+### Privileged notifiers
+
+Privileged notifiers follow the same pattern as privileged monitors. They cannot be added or removed by the AI coding agent via MCP tools (`superkick_add_notifier`, `superkick_remove_notifier`). They are also hidden from AI-facing responses (`list_notifiers`, `discover_notifiers`).
+
+Two levels of protection:
+
+1. **By name** — set `name:` and `privileged: true` on a notification config:
+```yaml
+notifications:
+  - type: slack
+    name: audit_channel
+    privileged: true
+    token: <%= env("SLACK_BOT_TOKEN") %>
+    channel: "#audit"
+```
+
+2. **By type** — use the hash form of `notifications:` with `privileged_types`:
+```yaml
+notifications:
+  privileged_types:
+    - datadog
+  items:
+    - type: datadog
+      statsd_host: localhost
+    - type: terminal_bell
+```
+
+The `notifications:` section supports both array form (existing) and hash form with `privileged_types` and `items` keys. Enforcement happens at the server's control layer (`Control::Server`) via `notifier_hidden?` and `raise_if_notifier_privileged!` helper methods, mirroring the monitor equivalents. Configuration provides `notifier_privileged?(name)` and `notifier_type_privileged?(type)` query methods.
+
+Driver-related state (`cli_command`, `prompt_patterns`, `injection_guards`) lives on the driver instance, not on Configuration. Access via `Superkick.driver`.
+
+`Superkick.reset_config!` rebuilds the configuration and clears the active driver — used in tests.
+
+### Template resolution
+
+Templates are resolved in this order:
+1. `~/.superkick/templates/<monitor_name>/<event_type>.liquid` — user per-instance override
+2. `~/.superkick/templates/<monitor_type>/<event_type>.liquid` — user per-type override
+3. `<Monitor.templates_dir>/<event_type>.liquid` — bundled per-type default
+
+This lets named instances (e.g. `disk-check`) have their own templates while sharing bundled defaults from the type (`shell/`).
+
+**Notification templates** are resolved separately via `TemplateRenderer.resolve_notification(notifier_class, event_type)`:
+1. `~/.superkick/templates/notifications/<type>/<event_type>.liquid` — user per-event override
+2. `<Notifier.templates_dir>/<event_type>.liquid` — bundled per-event
+3. `~/.superkick/templates/notifications/<type>/default.liquid` — user default catch-all
+4. `<Notifier.templates_dir>/default.liquid` — bundled default catch-all
+
+### Liquid Drops
+
+Monitors and spawners that dispatch **nested objects** (e.g. members, tasks, comments, check runs) wrap them in `Liquid::Drop` subclasses before dispatching. This is an implementation detail of the monitor/spawner — there is no shared interface or registry for Drops.
+
+**Why Drops are needed:** `TemplateRenderer.build_assigns` stringifies only top-level event hash keys. Nested hashes retain symbol keys, but Liquid resolves `{{ obj.prop }}` as `obj["prop"]` (string key lookup), so symbol-keyed nested hashes silently return `nil`. Drops provide method-based access that Liquid calls correctly.
+
+**When to use Drops:** Wrap nested objects in Drops when templates need dot-notation access on them (`{{ member.display_name }}`, `{{ check.name }}`). Scalar values at the top level of the event hash don't need Drops — `build_assigns` handles them.
+
+**Drops vs Filters:** Property access and formatting on individual objects → Drop methods (e.g. `{{ pull_request.ref }}`, `{{ story.ref }}`, `{{ member.tag }}`). Array operations that can be expressed in pure Liquid (`{{ owners | map: "tag" | join: ", " }}`) should use built-in Liquid filters rather than custom ones. Custom filters should only be added when they provide something impossible or cumbersome to express in pure Liquid — if a built-in filter chain works, prefer that over a new custom filter.
+
+Current Drops:
+
+Core Drops (used in notification payloads):
+- `Superkick::MonitorDrop` — `name`, `type` (wraps monitor identity in payloads)
+- `Superkick::TeamDrop` — `id`, `members` (wraps team context in payloads)
+- `Superkick::SpawnerDrop` — `name` (wraps spawner identity in payloads)
+- `Superkick::AgentDrop` — `id`, `role`, `team_role`, `spawned_at`, `cost_usd`, `claimed`, `goal` (nested GoalDrop)
+- `Superkick::GoalDrop` — `status`, `summary` (nested under AgentDrop)
+
+Integration Drops:
+- `Superkick::Integrations::GitHub::IssueDrop` — `number`, `title`, `body`, `url`, `author`, `labels`, `assignees`, `milestone`, `created_at`, `updated_at`
+- `Superkick::Integrations::GitHub::PullRequestDrop` — `number`, `title`, `ref` (formatted: `#42 "Title…"`)
+- `Superkick::Integrations::GitHub::CommentDrop` — `author`, `body`, `url`
+- `Superkick::Integrations::GitHub::ReviewDrop` — `author`, `state`, `body`, `url`
+- `Superkick::Integrations::GitHub::CommitDrop` — `message`, `author`, `url`
+- `Superkick::Integrations::GitHub::CheckRunDrop` — `name`, `conclusion`, `app`, `details_url`, `html_url`
+- `Superkick::Integrations::Shortcut::StoryDrop` — `id`, `name`, `url`, `ref`, `description`, `type`, `workflow_state`, `labels`, `owners`, `epic_name`, `tasks`, `comments`
+- `Superkick::Integrations::Shortcut::MemberDrop` — `display_name`, `mention_name`, `tag`
+- `Superkick::Integrations::Shortcut::TaskDrop` — `description`, `complete`
+- `Superkick::Integrations::Shortcut::CommentDrop` — `author` (returns MemberDrop), `body`, `created_at`
+- `Superkick::Integrations::Slack::MessageDrop` — `text`, `sender` (nested UserDrop), `channel` (nested ChannelDrop), `message_ts`, `thread_ts`, `ref` (formatted: `@Alice in #engineering`)
+- `Superkick::Integrations::Slack::UserDrop` — `id`, `name`, `tag` (formatted: `Display Name (<@U123>)`)
+- `Superkick::Integrations::Slack::ChannelDrop` — `id`, `name`, `ref` (formatted: `#channel-name`)
+- `Superkick::Team::LogEntryDrop` — `timestamp`, `category`, `agent_id`, `agent_role`, `role`, `message`, `kind`, `target_agent_id`, `artifact_name`
+
+## Development workflow
+
+### Claude Code sandbox bootstrap
+
+When running in the hosted Claude Code sandbox (`/home/user` base, rbenv at
+`/opt/rbenv`), Ruby 3.4.x is **not pre-installed** — only older versions
+(3.1–3.3) ship in the image. You must compile Ruby 3.4 from source via
+`rbenv install`, which takes several minutes. **Start this in the background
+immediately** so it finishes while you read the codebase.
+
+```bash
+# 1. Kick off Ruby 3.4 compilation in the background (takes ~2-4 min).
+export PATH="/opt/rbenv/bin:/opt/rbenv/shims:$PATH"
+rbenv install 3.4.4 &    # runs in background
+
+# 2. Once the install finishes, activate it and install gems.
+export RBENV_VERSION=3.4.4
+export PATH="/opt/rbenv/shims:$PATH"
+
+# IMPORTANT: Bundler 4.0.6 (shipped in Gemfile.lock) has a known bug
+# with Ruby 3.4 — `uninitialized class variable @@accept_charset in CGI`.
+# Work around it by installing and pinning Bundler 2.6.x:
+gem install bundler -v 2.6.7
+bundle _2.6.7_ install
+
+# Now bundle exec works normally.
+bundle exec rake test
+```
+
+Skip this section on developer machines where rbenv is properly initialised.
+
+### Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run the full test suite (core + per-integration, excludes integration/e2e)
+bundle exec rake test
+
+# Run core unit tests only
+bundle exec rake test:core
+
+# Run cross-component integration tests
+bundle exec rake test:integration
+
+# Run a single test file
+bundle exec rake test TEST=test/injector_test.rb
+
+# Run a specific test by name
+bundle exec rake test TEST=test/injector_test.rb TESTOPTS="-n test_returns_skipped_when_gate_refuses"
+
+# Run all tests matching a pattern
+bundle exec rake test TESTOPTS="-n /injection/"
+
+# Lint with Standard.rb
+bundle exec rake standard
+
+# Auto-fix lint violations
+bundle exec rake standard:fix
+
+# Run tests + lint (the default)
+bundle exec rake
+```
+
+## Test conventions
+
+- Framework: **Minitest::Spec** (`minitest/autorun`) — uses the Spec DSL for structure with assertion syntax for verification
+- Core tests live in `test/`, one file per class, named `<class>_test.rb`. Per-integration tests are colocated with their integration code at `lib/superkick/integrations/<name>/test/` (excluded from the gem via gemspec)
+- Cross-component integration tests live in `test/integration/`. These test the seams between components (spawn pipeline, server-agent IPC, injection flow) rather than individual component logic. Run via `bundle exec rake test:integration`
+- `test_helper.rb` creates a `TEST_HOME` tmpdir and sets `SUPERKICK_DIR` to it, so tests never touch `~/.superkick`
+- `Superkick.logger` is silenced (`Logger.new(File::NULL)`) in tests
+- `Superkick.reset_config!` is called in `test_helper.rb` and in any test that touches configuration
+- HTTP calls are mocked with **Faraday's test adapter** (`Faraday::Adapter::Test`). All HTTP-making classes (monitors, spawners, notifiers, `Hosted::Control::Client`) accept a `connection:` (or `client:` for Octokit-based classes) constructor parameter. Tests create a `Faraday::Adapter::Test::Stubs` instance, build a Faraday connection with the test adapter, and inject it via the constructor. Use `strict_mode: false` on stubs when the same stub should be reusable across multiple calls. No WebMock — the `webmock` gem is not a dependency
+- Tests that need a real Unix socket server typically spin up a thread in `before` and tear it down in `after`
+- **Parallel execution:** Test files that have no global state mutations use `parallelize_me!` at the top of the outermost `describe` block. A file is NOT safe to parallelize if it: mutates `Superkick.config`, calls `Superkick.reset_config!`, uses class-level `SomeClass.stub(:method, ...)` (replaces the method for ALL threads, not just the calling thread), writes to shared filesystem paths under `TEST_HOME`, swaps global objects like `$stderr`, or spawns background threads that perform registry lookups (e.g. Supervisor tests). Registry mutations alone are no longer a blocker — use `snapshot_registry`/`restore_registry` to isolate them (see "Registry test isolation" under Plugin registries)
+
+### E2E testing philosophy
+
+E2E tests (`test/e2e/`) exercise the production workflow as a **black box**. They are the highest-value tests in the suite and must follow these principles:
+
+1. **Maximize production fidelity.** E2E tests should exercise as much of the real production code path as possible. Use the same configuration options a normal user would (`config.yml` settings, CLI flags, MCP tool calls). If a feature is user-configurable, configure it the way a user would — don't bypass configuration by manually wiring internal components.
+
+2. **Prefer new test tooling over stubs.** When an E2E test needs to simulate an external system (e.g. a fake agent process, a fake PTY, a mock HTTP endpoint), build reusable test infrastructure (like `FakeAgent` in `test/e2e/support/`) rather than stubbing individual methods or manually constructing internal objects. It is ALWAYS preferable to introduce new tooling or behavior in the test harness to enable a more black-box test than to stub or manually configure individual components that aren't manually configurable by an end user.
+
+3. **Assert on observable behavior, not internals.** Check what the user would see or what the system produces — injected prompt text, IPC messages, file contents, MCP tool responses. Never inspect instance variables, private state, or intermediate data structures. When asserting on rendered output, verify the actual content (e.g. the message text), not just structural markers (e.g. a header keyword). Fuzzy assertions hide bugs — the `grouped` symbol-key bug went undetected because the test only checked for `"BLOCKERS"` instead of the actual blocker message.
+
+4. **Fix production bugs immediately.** When an E2E test reveals a bug in production code, fix it right then. Do not work around it in the test, ignore it, or defer it unless it requires substantial architectural changes — in that case, add it to the icebox with a clear description. The default is always to fix it.
+
+5. **Test the full injection pipeline.** For injection-related tests, verify the complete path: monitor tick → event dispatch → template rendering → buffer enqueue → injection queue drain → PTY write. The `FakeAgent` infrastructure enables this by providing a real `Buffer::Server`, `InjectionQueue`, and injectable PTY sink.
+
+### Minitest::Spec style
+
+All tests use the **Spec DSL for structure** (`describe`/`it`/`before`/`after`) but keep **assertion syntax everywhere** (`assert_*`/`refute_*`). No expectation-style syntax (`_()`, `must_*`, `wont_*`). No `let` — use instance variables in `before` blocks.
+
+| Element | Syntax |
+|---------|--------|
+| Test class | `describe Superkick::Foo do` |
+| Setup | `before do` |
+| Teardown | `after do` |
+| Test method | `it "does something" do` |
+| Test grouping | Nested `describe "group name" do` blocks |
+| Assertions | `assert_*` / `refute_*` (never expectations) |
+| Test state | Instance variables in `before` (never `let`) |
+| Helper methods | Regular `def` methods inside `describe` blocks |
+| Inner stub classes | Class definitions inside `describe` blocks |
+| Parallel execution | `parallelize_me!` inside `describe` block |
+
+Example:
+```ruby
+describe Superkick::Foo do
+  before do
+    @foo = Superkick::Foo.new
+  end
+
+  describe "some feature" do
+    it "does the thing" do
+      assert_equal :expected, @foo.do_thing
+    end
+  end
+end
+```
+
+### Stubbing and test doubles
+
+- **Use Minitest's `stub` method** for replacing methods during tests: `SomeClass.stub(:method_name, return_value) { ... }`. This is block-scoped and automatically restores the original method.
+- **Never use `define_singleton_method`** to stub methods on classes or instances. It pollutes state and persists beyond the test — there is no automatic cleanup like `stub` provides. Always use Minitest's `stub` method instead, which is block-scoped and restores the original automatically. The only acceptable use of `define_singleton_method` is inside a `Class.new` block to define methods on a fresh anonymous class that needs closure access (e.g. capturing a local variable for `templates_dir`). Even then, prefer `def self.method_name` when no closure is needed.
+- **Do not introspect private APIs or state** in tests. Do not use `instance_variable_set` or `instance_variable_get` to reach into objects. Either test behavior through existing public interfaces, or expose what you need through new public methods.
+- **Use `capture_io`** (from Minitest) to capture stdout/stderr. Do not write custom `capture_stdout` or `capture_stderr` helpers — Minitest provides `capture_io { ... }` which returns `[stdout, stderr]`.
+- **Use `snapshot_registry`/`restore_registry`** to isolate registry mutations in tests. Never use `deregister` for test cleanup — snapshot/restore is cleaner and handles all entries atomically. See "Registry test isolation" under Plugin registries.
+
+## Extending Superkick
+
+### Adding a new driver
+
+A driver describes how to drive a specific AI CLI. See `skills/superkick-new-driver/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/drivers/my_cli.rb` — subclass `Superkick::Driver`
+2. Implement `self.driver_name`, `initialize(**opts)`, and instance methods (`cli_command`, `prompt_patterns`, etc.)
+3. Optionally implement `cost_patterns` → Array of `CostPattern` for PTY cost extraction, and `cost_command` → String (e.g. `/cost`) for the CostPoller to inject
+4. Implement `apply_config_dir(config_dir, env:, args:)` to set the CLI's config directory env var or flag
+5. Override `install_mcp(exe_path:)` to configure the CLI's MCP settings
+5. Register: `Superkick::Driver.register(Superkick::Drivers::MyCli)`
+6. Require in `lib/superkick/drivers.rb`
+
+### Adding a new monitor
+
+See `skills/superkick-new-monitor/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/integrations/<name>/monitor.rb` — subclass `Superkick::Monitor`, implement `self.type`, `self.required_config`, `self.templates_dir`, `tick`
+2. Optionally create `lib/superkick/integrations/<name>/probe.rb` — define `MyMonitor::Probe < Monitor::Probe`, implement `self.type`, `self.environment_actions`, `self.detect(environment:)`. Probes return `{ monitor_name: { type: "…", config } }` (symbol keys). Probes run server-side using an environment snapshot, not with direct filesystem access.
+3. Create `lib/superkick/integrations/<name>.rb` — requires both files, calls `Superkick::Monitor.register(MyMonitor)`
+4. Add Liquid templates in `lib/superkick/integrations/<name>/templates/`
+5. Require the entry point in `lib/superkick.rb`
+6. Optionally implement `self.setup_label` and `self.setup_config` to appear in `superkick setup`
+7. Optionally package as a gem and load via `plugins:` in `config.yml`
+
+### Adding a new notifier
+
+A notifier alerts the user after a successful injection. See `skills/superkick-new-notifier/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/notifiers/my_notifier.rb` — subclass `Superkick::Notifier`
+2. Implement `self.type` and `notify(payload)`
+3. Register: `Superkick::Notifier.register(Superkick::Notifiers::MyNotifier)`
+4. Require in `lib/superkick.rb` under the notifiers section
+5. Optionally implement `self.setup_label` and `self.setup_config` to appear in `superkick setup`
+
+### Adding a new spawner
+
+A spawner is a server-level poller that spawns new agents in response to external events. See `skills/superkick-new-spawner/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/integrations/<name>/spawner.rb` — subclass `Superkick::Spawner`, implement `self.type`, `self.required_config`, `self.agent_id(event)`, `tick`
+2. Optionally create spawn templates in `lib/superkick/integrations/<name>/templates/`
+3. Create the entry point and register: `Superkick::Spawner.register(MySpawner)`
+4. Require in `lib/superkick.rb` under the integrations section
+5. Optionally implement `self.setup_label` and `self.setup_config` to appear in `superkick setup`
+
+### Adding a new goal
+
+A goal defines what "finished" means for a spawned agent. See `skills/superkick-new-goal/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/goals/my_goal.rb` — subclass `Superkick::Goal`
+2. Implement `self.type` and `check` (return one of `STATUSES`)
+3. Optionally implement `teardown` for cleanup
+4. Self-register at the bottom of the file: `Superkick::Goal.register(Superkick::Goals::MyGoal)`
+5. Require in `lib/superkick.rb` under the goals section
+
+### Adding a new version control adapter
+
+A version control adapter knows how to acquire an isolated working copy of a repository and clean it up afterwards. See `skills/superkick-new-version-control/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/integrations/<name>/version_control.rb` — subclass `Superkick::VersionControl`
+2. Implement `self.type`, `acquire(source:, destination:, branch:, base_branch:)`, and `teardown(destination:)`
+3. Self-register at the bottom of the file: `Superkick::VersionControl.register(Superkick::Integrations::MyVcs::VersionControl)`
+4. Require in `lib/superkick.rb` under the integrations section
+
+### Adding a new repository source
+
+A repository source discovers and describes repositories for team planning and spawned agent workspaces. See `skills/superkick-new-repository-source/SKILL.md` for the full walkthrough. In brief:
+
+1. Create `lib/superkick/repository_sources/my_source.rb` (or in an integration directory) — subclass `Superkick::RepositorySource`
+2. Implement `self.type` and `repositories` (returns `{ name_sym => Repository }`)
+3. Self-register at the bottom of the file: `Superkick::RepositorySource.register(MySource)`
+4. Require in `lib/superkick.rb`
+
+### Built-in monitors
+
+- **`Integrations::GitHub::Monitor`** (`:github`) — polls CI checks, PR comments, PR reviews via Octokit. `resolve_config` fills in missing `repo` and `branch` from the environment snapshot (parsed via `parse_github_repo` from git remote data). Probe auto-detects repo/branch from the environment's git remote and branch data.
+- **`Integrations::CircleCI::Monitor`** (`:circleci`) — polls CircleCI pipelines and workflows for status changes via Faraday. Config: `project_slug` (required), `branch` (required), `token`. `resolve_config` fills in missing `project_slug` and `branch` from the environment snapshot (parsed via `parse_project_slug` from git remote data, plus `.circleci/config.yml` existence check). Probe auto-detects from the environment's file existence and git remote data.
+- **`Integrations::Shortcut::Monitor`** (`:shortcut`) — polls Shortcut stories for state changes, comments, blockers, owner changes, and description updates via Faraday. Also watches linked stories and epic siblings for state changes. Config: `token`, `workspace_slug`, `member`, `ignore_self`. `resolve_config` fills in missing `story_id` from the `sc-XXXXX` branch pattern in the environment snapshot's git branch data. Probe auto-detects `story_id` from the environment's git branch name.
+- **`Integrations::Shell::Monitor`** (`:shell`) — runs a shell command each tick, dispatches `shell_alert` on non-zero exit or `shell_success` when `report_success` is enabled. Config: `command` (required), `working_dir`, `timeout`, `report_success`. No probe — shell monitors must be explicitly configured. `resolve_config` resolves bare command names (without path separators) relative to `.superkick/shell/` in the agent's working directory. Supports multiple instances under different names.
+- **`Integrations::Datadog::AlertMonitor`** (`:datadog_alert`) — polls a specific Datadog monitor for status changes and injects events when the alert state transitions. Dispatches `alert_recovered` (→ OK), `alert_escalated` (Warn → Alert), or `alert_changed` (any other transition). Config: `monitor_id` (required), `site` (optional), `api_key` (optional, falls back to `DD_API_KEY`), `application_key` (optional, falls back to `DD_APP_KEY`). Records baseline on first tick and only dispatches on state changes.
+- **`Integrations::Slack::ThreadMonitor`** (`:slack_thread`) — polls Slack `conversations.replies` for new messages in a specific thread. Designed to be auto-attached to agents spawned by the Slack spawner via the `_spawn_monitors` mechanism. Dispatches `slack_reply` events with `injection_priority: :high, injection_ttl: 900`. Config: `channel_id` (required), `thread_ts` (required), `token`. Uses Faraday for HTTP.
+
+### Built-in spawners
+
+- **`Integrations::Shortcut::Spawner`** (`:shortcut`) — watches Shortcut for stories matching a search query and spawns agents. Config: `query` (required), `token`, `workspace_slug`, `owner`, `label`.
+- **`Integrations::GitHub::IssueSpawner`** (`:github_issues`) — watches GitHub for newly created or reopened issues and spawns agents to work on them. Uses an `updated_at` watermark so reopened issues are caught automatically. Config: `repo` (required), `token`, `labels` (array, AND filter), `assignee` (username, `"*"`, or `"none"`), `milestone`, `creator`, `exclude_pull_requests` (default true). Agent ID format: `github-issue-{org}-{repo}-{number}`. Pairs naturally with the `:github_issue_resolved` goal.
+- **`Integrations::GitHub::CheckFailedSpawner`** (`:github_check_failed`) — watches GitHub check suites for failures on configured branches and spawns agents to fix them. Works across CI providers since it polls GitHub's check runs API. Config: `repo` (required), `branches` (required, array of branch names), `token`, `app_filter` (array of app names/slugs to include), `check_name_filter` (array of check run names to include), `exclude_apps` (array of app names to ignore). Agent ID format: `github-check-{org}-{repo}-{branch}-{short_sha}` — unique per branch+commit so a new failure after a push gets a new agent.
+- **`Integrations::Bugsnag::Spawner`** (`:bugsnag`) — watches Bugsnag for open errors and spawns agents to fix them. Polls the Bugsnag Data Access API with configurable filters. Config: `project_id` (required), `token` (optional, falls back to `BUGSNAG_TOKEN`), `severity` (array, default `["error"]`), `release_stage` (string, default `"production"`), `minimum_events` (integer, default 1), `error_classes` (hash with `include`/`exclude` arrays for server-side and client-side filtering), `versions` (array, supports `"latest"` which resolves via the releases API), `filters` (hash of additional Bugsnag API filter fields as passthrough). Agent ID format: `bugsnag-error-{error_id}`.
+- **`Integrations::Datadog::Spawner`** (`:datadog`) — watches Datadog Error Tracking for open error groups and spawns agents to fix them. Polls the Datadog Error Tracking API with configurable filters. Config: `site` (optional, default `"datadoghq.com"`), `api_key` (optional, falls back to `DD_API_KEY`), `application_key` (optional, falls back to `DD_APP_KEY`), `service` (optional, filter by service name), `environment` (optional, default `"production"`), `source` (optional, e.g. `"ruby"`), `minimum_events` (integer, default 1), `query` (optional, raw Datadog search query). Agent ID format: `datadog-error-{group_id}`.
+- **`Integrations::Datadog::AlertSpawner`** (`:datadog_alerts`) — watches Datadog monitors for triggered alerts and spawns agents to triage them. Polls the Datadog Monitors Search API for monitors in an alerting state. Monitors that recover and re-alert are re-dispatched as new agents. Config: `site` (optional, default `"datadoghq.com"`), `api_key` (optional, falls back to `DD_API_KEY`), `application_key` (optional, falls back to `DD_APP_KEY`), `statuses` (array, default `["Alert"]`), `tags` (array, AND filter), `monitor_types` (array, e.g. `["metric", "log"]`), `priority` (array of priority levels 1-5), `query` (optional, raw search query). Agent ID format: `datadog-alert-{monitor_id}`. Pairs naturally with the `:datadog_alert_resolved` goal and `:datadog_alert` monitor.
+- **`Integrations::Honeybadger::Spawner`** (`:honeybadger`) — watches Honeybadger for unresolved faults and spawns agents to fix them. Polls the Honeybadger Faults API with configurable filters. Config: `project_id` (required), `token` (optional, falls back to `HONEYBADGER_TOKEN`), `environment` (optional, default `"production"`), `minimum_occurrences` (integer, default 1), `fault_classes` (array or include/exclude hash for server-side and client-side filtering). Agent ID format: `honeybadger-fault-{fault_id}`.
+- **`Integrations::Slack::Spawner`** (`:slack`) — watches a Slack channel for new messages and spawns agents to handle them. Polls Slack `conversations.history` via Faraday. Auto-attaches a `:slack_thread` monitor to each spawned agent via the `_spawn_monitors` mechanism, so the agent receives high-priority injections when replies arrive in the originating thread. Also auto-attaches a per-agent Slack notifier via the `_spawn_notifiers` mechanism with a pre-seeded `thread_ts` pointing to the originating message, so lifecycle notifications for the agent are threaded under the original Slack message. Both the thread monitor and per-agent notifier are skipped when `monitor_thread: false`. Config: `channel` (required — channel ID), `token`, `channel_name`, `filter_pattern` (regex to filter messages), `ignore_bots` (default true), `ignore_threads` (default true — only top-level messages), `monitor_thread` (default true — auto-attach thread monitor and per-agent notifier). Agent ID format: `slack-message-{channel_id}-{ts}`.
+
+## Hash key conventions
+
+All internal hashes use **Symbol keys**. This is enforced at deserialization boundaries and must be maintained when writing new code.
+
+### Rules
+
+1. **Internal hashes always use Symbol keys.** Config hashes, event hashes, monitor hashes, agent data — all Symbol-keyed. Use `%i[...]` for symbol arrays (e.g. `required_config`), not `%w[...]`.
+
+2. **Symbolize at deserialization boundaries:**
+   - **JSON** — use `JSON.parse(str, symbolize_names: true)` when parsing internal data (IPC messages, agent files, config persistence).
+   - **YAML** — use `YAML.safe_load(str, symbolize_names: true)`. The `YamlConfig` loader does this at the YAML boundary.
+   - **Control messages** — `Connection` already uses `symbolize_names: true`, so all received messages have symbol keys.
+
+3. **External API responses keep string keys.** Data from third-party APIs (GitHub/Octokit, Shortcut, CircleCI) comes through `JSON.parse` without `symbolize_names` and stays as string-keyed hashes (e.g. `story["name"]`, `pipeline["id"]`). Do NOT symbolize these — they're consumed locally within the monitor and never stored or passed to internal interfaces.
+
+4. **No defensive dual-key access.** Never write `cfg["type"] || cfg[:type]` or `cfg.fetch("key") rescue cfg.fetch(:key)`. Pick one (Symbol) and trust it.
+
+5. **No unnecessary key conversions.** Do not sprinkle `transform_keys(&:to_s)`, `transform_keys(&:to_sym)`, or `.to_s` / `.to_sym` throughout the code. If you find yourself needing a conversion, the data was constructed wrong upstream — fix it there instead.
+
+6. **Config accessor uses Symbol lookup.** The `Monitor#[]` accessor converts to symbol: `@config[key.to_sym]`. Callers should use `self[:key]` (symbol), not `self["key"]` (string).
+
+7. **Probes return Symbol-keyed hashes.** e.g. `{ github: { type: "github", branch: branch, repo: repo } }`.
+
+### Quick reference
+
+```ruby
+# Good
+config = { branch: "main", repo: "org/repo" }
+JSON.parse(data, symbolize_names: true)
+self[:token]
+required_config = %i[branch repo]
+
+# Bad
+config = { "branch" => "main", "repo" => "org/repo" }
+JSON.parse(data)  # for internal data — missing symbolize_names
+self["token"]
+required_config = %w[branch repo]
+config.transform_keys(&:to_sym)  # shouldn't be needed
+```
+
+## Code style conventions
+
+Superkick targets **Ruby >= 3.4** and uses modern Ruby idioms throughout. Follow these when writing new code.
+
+### No abbreviated names in public APIs
+
+**Do NOT abbreviate names**, especially in public APIs, config keys, method names, class names, and MCP tool parameters. Always use the full word.
+
+```ruby
+# Good
+repository_source
+repositories
+Integrations::GitHub::OrganizationRepositorySource
+:github_organization
+:version_control
+repository_name
+repository_context
+
+# Bad — abbreviated
+repo_source
+repos
+GithubOrgRepositorySource
+:github_org
+:ver_ctrl
+repo_name
+repo_context
+```
+
+This applies to all identifiers: class names, method names, variable names, config keys, YAML keys, MCP tool parameter names, event hash keys, and template variable names. Internal local variables in small scopes may use shorter names when clarity is obvious, but when in doubt, spell it out.
+
+### Implicit `it` block parameter (Ruby 3.4)
+
+Use `it` instead of a named block parameter in single-parameter blocks where the body is short (one expression or a simple one-liner):
+
+```ruby
+# Good — single-param block, simple body
+threads.each_value { it.each_value(&:kill) }
+agents.each { yield it }
+guards.transform_values { it[:reason] }
+patterns.any? { it.match?(stripped_text) }
+Thread.new(connection) { handle(it) }
+monitors.each_key { start_agent_monitor(agent_id, it) }
+workflows.select { TERMINAL_STATUSES.include?(it["status"]) }
+
+# Bad — unnecessary named parameter
+threads.each_value { |t| t.each_value(&:kill) }
+agents.each { |agent| yield agent }
+Thread.new(connection) { |conn| handle(conn) }
+```
+
+Keep named parameters when:
+- The block has **multiple parameters** (e.g. `each_with_object`, `reject! { |_, v| ... }`)
+- The block body is **multi-line** and a name aids readability (e.g. long `do...end` blocks)
+- The parameter is **destructured** (e.g. `|key, value|`)
+
+### Keyword argument shorthand (value punning)
+
+When a keyword argument name matches the local variable being passed, use the shorthand:
+
+```ruby
+# Good
+dispatch(event_type:, project_slug:, branch:)
+Injector.new(store:)
+Agent.new(id:, registered_at:)
+
+# Bad
+dispatch(event_type: event_type, project_slug: project_slug, branch: branch)
+Injector.new(store: store)
+```
+
+### Hash literal shorthand
+
+Same rule applies to hash literals when the key matches the variable name:
+
+```ruby
+# Good
+{ seconds_idle:, at_prompt: }
+{ ok: true, seconds_idle:, at_prompt: }
+
+# Bad
+{ seconds_idle: seconds_idle, at_prompt: at_prompt }
+```
+
+### `attr_reader` over trivial getters
+
+Use `attr_reader` instead of defining trivial reader methods:
+
+```ruby
+# Good
+attr_reader :idle_state
+
+# Bad
+def idle_state = @idle_state
+def idle_state; @idle_state; end
+```
+
+### Nil-safe guards
+
+Prefer `&.` (safe navigation) and guard clauses over verbose nil checks:
+
+```ruby
+# Good
+@worker&.join(5)
+return unless agent
+
+# Bad
+@worker.join(5) if @worker
+```
+
+### Empty-line between method definitions
+
+StandardRB requires a blank line between method definitions, even in compact test stubs:
+
+```ruby
+# Good
+def initialize
+  @dispatched = []
+end
+
+def inject(agent_id:, event:)
+  @dispatched << event
+end
+
+# Bad — missing blank line
+def initialize
+  @dispatched = []
+end
+def inject(agent_id:, event:)
+  @dispatched << event
+end
+```
+
+## Documentation requirements
+
+**ALWAYS review and update documentation after every implementation change.** This is not optional — treat documentation updates as part of the implementation, not a follow-up task. Incomplete documentation is a bug.
+
+For the full documentation update procedure, see the **`superkick-update-docs`** skill at `skills/superkick-update-docs/SKILL.md`. It contains detailed mapping of which implementation changes require which documentation updates. The summary below covers the essentials.
+
+### What to review after every change
+
+1. **`README.md`** — the root-level README is the public-facing documentation. When adding or modifying integrations, spawners, monitors, goals, drivers, notifiers, CLI commands, MCP tools, or configuration settings, update the corresponding section. New integrations MUST get an entry under "Built-in integrations" following the existing pattern.
+
+2. **`CLAUDE.md`** (this file) — update the architecture docs, directory structure, key classes, configuration tables, and extension guides to reflect any structural or behavioral changes. New files should appear in the directory structure listing. New classes should get a "Key classes" entry if they are architecturally significant.
+
+3. **Integration-level READMEs** (e.g. `lib/superkick/integrations/github/README.md`) — when adding a new integration, create a README. When updating an existing integration, review and update its README.
+
+4. **Skills** (`skills/superkick-new-<type>/SKILL.md`) — each plugin registry (Driver, Monitor, Spawner, Goal, Notifier, VersionControl) has a matching skill that walks through adding a new implementation. When you introduce a new extension point or significantly change the contract for an existing one, create or update the corresponding skill.
+
+5. **`CONTRIBUTING.md`** — update if contribution workflows, development setup, or testing patterns change.
+
+6. **User-facing docs** (`docs/`) — the `docs/` directory contains user-facing documentation organized by the Diataxis framework. Planning documents live in `docs/planning/` and are not published. Specific documents to evaluate:
+
+   - **Tutorials** (`docs/tutorials/`) — update when the user experience changes:
+     - `getting-started.md` — installation, basic config, first-run experience
+     - `first-spawner-pipeline.md` — spawner config, goal config, repository acquisition, workflow syntax
+     - `team-workflow.md` — team mechanics, repository source config, MCP team tools
+
+   - **How-to guides** (`docs/how-to/`) — update when task-oriented procedures change:
+     - `customize-templates.md` — template resolution, Liquid filters, template directory structure
+     - `configure-notifications.md` — notifier types, event filtering, SUPERKICK_* env vars
+     - `troubleshooting.md` — new failure modes, changed error messages, new diagnostic commands
+
+   - **Explanations** (`docs/explanation/`) — update when system behavior or design changes:
+     - `injection-model.md` — PTY proxy, idle detection, guards, injection sequence
+     - `spawner-workflows.md` — goal statuses, workflow chaining, VCS inheritance
+     - `agent-teams.md` — planning agent, team log, team config, claim/unclaim
+
+   - **Reference** (`docs/reference/`) — update when APIs, events, or template variables change:
+     - `templates.md` — template variables per event type (update whenever a `dispatch()` call changes)
+     - `event-types.md` — all event types and payloads (update whenever events are added/removed/renamed)
+
+### Checklist
+
+Before considering any implementation task complete, verify:
+- [ ] `README.md` reflects the change (new features, integrations, commands, config options)
+- [ ] `CLAUDE.md` reflects the change (architecture, classes, directory structure)
+- [ ] Integration READMEs are created or updated as needed
+- [ ] `docs/reference/templates.md` updated if template variables changed
+- [ ] `docs/reference/event-types.md` updated if event types changed
+- [ ] `docs/tutorials/` updated if user experience or config syntax changed
+- [ ] `docs/how-to/` updated if procedures, notifications, or troubleshooting patterns changed
+- [ ] `docs/explanation/` updated if system behavior or design changed
+- [ ] Skills are created or updated for new/changed extension points
+- [ ] Configuration tables are updated if settings were added or changed
+- [ ] New documentation evaluated — explicitly state whether new tutorials, how-to guides, explanations, or reference pages are recommended for the change (see `skills/superkick-update-docs/SKILL.md` for evaluation criteria)
+- [ ] `docs/planning/README.md` (roadmap) updated if a roadmap item was completed or priorities changed
+
+## Design principles
+
+- **Prefer the right solution over the least invasive one.** When choosing between approaches, lean towards the architecturally correct design rather than the quickest path, always considering the future product vision and roadmap. Superkick is headed towards a SaaS architecture with multiple server instances — designs that rely on global state, singletons, or class-level variables will break at scale. Constructor injection, instance-level state, and explicit dependency passing are preferred over hidden global state, even when they touch more files.
+
+## Things that trip you up
+
+- **Monitor name vs type.** The `:type` key in monitor config is reserved — it identifies the monitor class. Monitor names are the per-agent unique keys (Symbols). When `:type` is absent, the name is used as the type.
+- **`SUPERKICK_DIR` is everything.** The base dir path is baked into `Configuration` at init time. If you change it mid-process you must call `Superkick.reset_config!`.
+- **The server must be running for injection to work.** `superkick agent` still works without the server — it just prints a log line and continues.
+- **Buffer sockets are transient.** They exist only while `superkick agent` is active. The server stores the path in the `Agent` object; it's nil until the agent registers. Runtime sockets live in `~/.superkick/run/`. In hosted mode, the buffer channel uses a WebSocket instead of a Unix socket — the `Hosted::Buffer::Bridge` in the agent connects to the server's `Hosted::Buffer::Relay`.
+- **Client factories live on the namespace modules.** `Buffer.client_from`, `Control.client_from`, and `Attach.client_from` select the right client class based on `config.server_type` (`:local` or `:hosted`). Each namespace module extends `ClientRegistry`, which provides `register_client` and `client_from`. Hosted subclasses self-register (e.g. `Hosted::Control::Client` registers as `:hosted` on `Control`). Never construct hosted subclasses directly outside of tests — always use `client_from`. Server-side components receive the constructed client via constructor injection (e.g. `buffer_client:`).
+- **Protocol framing.** `Connection` uses newline-delimited JSON. Don't hand-roll the protocol — it's shared by both control plane and data plane components.
+- **Frozen string literals everywhere.** All lib files have `# frozen_string_literal: true`. Don't use `<<` for string mutation; use `+` or `dup`.
+- **Standard.rb for linting.** Zero-config. Run `bundle exec rake standard:fix` to auto-fix, then review the diff. Don't add a `.rubocop.yml` — StandardRB manages that internally.
+- **Privileged monitors and notifiers are enforced at the server.** The MCP process does not load `config.yml`, so privilege checks live in `Control::Server`, not `McpServer`. For monitors: the `:privileged` key on a monitor config and the `privileged_types` list on Configuration are the sources of truth. For notifiers: the `:name` + `:privileged` keys on a notification config and `notification_privileged_types` on Configuration are the sources of truth.
+- **No backwards compatibility concerns.** This is a new tool with a single user. Feel free to rename, restructure, change config formats, or break APIs without deprecation shims. No need for migration paths, backwards-compatible aliases, or re-exported symbols. Just make the change directly. This policy will be explicitly revisited when the user base grows.
+- **Monitor probes use environment snapshots, not filesystem access.** Monitor probes run server-side using an environment snapshot (collected from the agent via `EnvironmentExecutor`). They take `environment:` not `dir:`. The agent collects environment data in response to action hashes sent by the server during registration. If you need new environment data for a monitor probe, add an action type to `EnvironmentExecutor` and declare it in `self.environment_actions`. VCS probes are different — they detect VCS type by inspecting the local filesystem directly via `detect_at(path:)` and are used by repository sources, not during agent registration.
+- **No abbreviated names.** Always use full words in identifiers — `repository` not `repo`, `organization` not `org`, `repositories` not `repos`. See the "No abbreviated names in public APIs" code style rule. This applies everywhere: class names, method names, config keys, MCP parameters, event keys, templates.