speexor 0.1.1 → 0.2.1

package/SECURITY-DEFAULTS.md

@@ -0,0 +1,118 @@
+# Security & Safety Defaults
+
+> Reference document for Speexor's two-layer security and safety model.
+> Created per FR-94 (PRD05 §4.5) to clarify the distinction between
+> Extension Permissions and Action Risk Tiers.
+
+## Overview
+
+Speexor has **two independent safety layers** that operate at different levels:
+
+1. **Extension Permissions** — gates what an extension *can ever do* (set once at install time)
+2. **Action Risk Tiers** — gates what *any* action (from any already-permitted extension or core agent) *does right now* (evaluated every time)
+
+These are intentionally separate systems. An extension that passes its permission check still has every runtime action evaluated against the Action Risk Tier policy.
+
+---
+
+## Layer 1: Extension Permissions
+
+### What it controls
+Capabilities granted to third-party extensions at install time.
+
+### Configuration
+`spexor.config.yaml` → `extensions.permissionsMode`
+
+| Mode | Behavior |
+|------|----------|
+| `strict` (default) | Extensions run in sandboxed process with enforced permission boundaries |
+| `relaxed` | Permissions still require user confirmation, but sandboxing is less restrictive |
+
+### Permission Axes
+
+| Axis | Levels | Default | Description |
+|------|--------|---------|-------------|
+| `fileSystem` | `none`, `read-only`, `read-write`, `scoped`, `full` | `none` | Access to the local file system |
+| `network` | `none`, `read-only`, `scoped`, `full` | `none` | Outbound network access |
+| `shell` | `none`, `read-only`, `scoped`, `full` | `none` | Shell command execution |
+| `secrets` | string[] of named scopes | `[]` | Access to named secrets in the Vault |
+
+### Permission Lifecycle
+1. **Install**: Extension manifest declares permissions → displayed to user in plain English
+2. **Confirm**: User explicitly accepts or rejects the permission set
+3. **Upgrade**: Any permission upgrade on update requires re-confirmation
+4. **Runtime**: PermissionEnforcer checks every operation against declared permissions
+
+### Enforcement
+- Extensions with `shell: none` + `network: none` → `IsolatedSandbox` (node:vm, no Node built-ins)
+- Extensions requiring broader access → `ProcessSandbox` (child_process with proxy)
+- `worker_threads` is NEVER used as a security boundary (it shares process memory)
+
+---
+
+## Layer 2: Action Risk Tiers
+
+### What it controls
+Whether a specific runtime action (from any source) requires user approval before execution.
+
+### Configuration
+`spexor.config.yaml` → `riskPolicy`
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `autoApprove` | `[]` | Action categories that auto-execute without approval |
+| `requireApproval` | `["irreversible-high-stakes"]` | Action categories that always require approval |
+| `approvalTimeout` | `4h` | How long an approval request waits before default action |
+| `approvalDefaultAction` | `skip` | What happens when approval times out |
+| `defaultRiskTierForUnknownActions` | `medium` | Default tier when action risk can't be classified |
+
+### Risk Tiers
+
+| Tier | Auto-Approve? | Examples |
+|------|---------------|----------|
+| `reversible-low` | Yes (default) | Running tests, linting, reading files |
+| `reversible-medium` | Yes (default) | Creating branches, committing code |
+| `irreversible-high-stakes` | No (requires approval) | Merging PRs, deleting branches, publishing packages, modifying CI config |
+| `unknown` | Depends on `defaultRiskTierForUnknownActions` | Actions not classified by the risk classifier |
+
+### Approval Workflow
+1. Action is evaluated by GovernanceEngine.evaluateAction()
+2. If requires approval → ApprovalItem created with expiry + default action
+3. Appears in dashboard "Approvals" panel (tagged as Axis 2)
+4. User approves/rejects or timeout triggers default action
+
+---
+
+## Comparison: When Each Layer Applies
+
+| Scenario | Extension Permissions | Action Risk Tier |
+|----------|----------------------|------------------|
+| Installing a code-review skill | ✅ Checked (install time) | ❌ Not applicable |
+| Skill reads a file in workspace | ✅ Checked (fileSystem permission) | ❌ Not applicable (reversible-low) |
+| Skill runs `git push` | ✅ Checked (shell permission) | ✅ Checked (irreversible-high-stakes) |
+| Skill makes HTTP call | ✅ Checked (network permission) | ❌ Not applicable (reversible-medium) |
+| Core agent creates a PR | ❌ Not applicable (core, not extension) | ✅ Checked (irreversible-high-stakes) |
+| Core agent proposes a new task | ❌ Not applicable | ✅ Checked (task-origin-gate, Axis 1) |
+
+---
+
+## Safety Defaults Summary
+
+| Default | Value | Rationale |
+|---------|-------|-----------|
+| Extension permissions default | All `none` | Least privilege by default |
+| Permissions mode | `strict` | Sandbox everything third-party |
+| Unknown risk tier | `medium` | Conservative when can't classify |
+| Approval timeout default action | `skip` | Fail safe, don't auto-execute |
+| Budget limit | Not set (opt-in) | User must explicitly set cost controls |
+| Auto-merge PRs | `false` | Human judgment required for merges |
+
+---
+
+## Related Documentation
+
+- [SECURITY.md](SECURITY.md) — Vulnerability reporting, incident response
+- [ARCHITECTURE.md](ARCHITECTURE.md) — System architecture and plugin model
+- [CONTRIBUTING.md](CONTRIBUTING.md) — Extension development guidelines
+- `src/sandbox/` — Sandbox implementation
+- `src/governance/` — Governance engine implementation

package/SECURITY.md

@@ -1,79 +1,80 @@
-# Security Policy
-
-## Supported Versions
-
-| Version | Supported |
-|---------|-----------|
-| 0.1.x   | ✅ Active development |
-
-## Reporting a Vulnerability
-
-Speexor handles API tokens (GitHub tokens, AI provider keys) and executes AI-generated code. Security is a top priority.
-
-**To report a vulnerability:**
-1. **Do NOT** open a public GitHub issue
-2. Email: opensource@superdevids.com (or use GitHub's private vulnerability reporting)
-3. Include a detailed description, steps to reproduce, and potential impact
-
-You can expect:
-- **Acknowledgment** within 48 hours
-- **Initial assessment** within 5 business days
-- **Fix timeline** depending on severity
-
-## Security Practices
-
-### Credential Management
-- API tokens are stored in environment variables or the system keychain
-- Secrets are never logged in plaintext
-- GitHub tokens are reused from `gh` CLI when possible
-- `.speexor/` directory is git-ignored (add to `.gitignore`)
-
-### Code Execution
-- AI agents generate and execute code in isolated git worktrees
-- Each agent runs in its own process/tmux session
-- Process runtime has resource limits (SIGTERM → SIGKILL after 5s)
-- Worktrees are cleaned up on session stop or package destroy
-
-### Network Security
-- Dashboard server listens on localhost by default
-- CORS is enabled (configurable in production)
-- No telemetry or tracking
-- No cloud dependency — fully local-first
-
-### Data Protection
-- Session state stored in `.speexor/state.json` (local only)
-- Logs stored in `.speexor/logs/` (local only)
-- No data sent to external servers except configured AI providers and GitHub API
-- Users control which API endpoints are called
-
-### Supply Chain Security
-- All dependencies are pinned with exact versions
-- pnpm lockfile for deterministic installs
-- Regular dependency audits via `pnpm audit`
-- Minimal runtime dependencies (12 packages)
-
-## Security Checklist for Deployments
-
-- [ ] AI provider API keys stored in environment variables (not config files)
-- [ ] GitHub tokens use minimal scopes (repo, issues, pull requests)
-- [ ] Dashboard port not exposed to public internet
-- [ ] `.speexor/` directory added to `.gitignore`
-- [ ] Regular dependency updates (`pnpm audit`)
-- [ ] Agent output reviewed before auto-merge (auto-merge disabled by default)
-
-## Third-Party Security
-
-Speexor relies on:
-- **GitHub CLI (`gh`)** — user's existing authentication
-- **AI agent CLIs** — OpenCode, Claude Code, Aider, Codex — each with their own security models
-- **tmux** (Unix) / **Process** (Windows) — for runtime isolation
-
-Review the security documentation for each tool you use.
-
-## Incident Response
-
-1. **Detection** — Monitoring for unusual agent behavior or unauthorized access
-2. **Containment** — `speexor stop <session>` to halt affected agents
-3. **Analysis** — Review logs in `.speexor/logs/` and session state
-4. **Recovery** — Rotate affected credentials, clean up worktrees
-5. **Postmortem** — Document findings, update security practices
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | ✅ Active development |
+
+## Reporting a Vulnerability
+
+Speexor handles API tokens (GitHub tokens, AI provider keys) and executes AI-generated code. Security is a top priority.
+
+**To report a vulnerability:**
+1. **Do NOT** open a public GitHub issue
+2. Email: opensource@superdevids.com (or use GitHub's private vulnerability reporting)
+3. Include a detailed description, steps to reproduce, and potential impact
+
+You can expect:
+- **Acknowledgment** within 48 hours
+- **Initial assessment** within 5 business days
+- **Fix timeline** depending on severity
+
+## Security Practices
+
+### Credential Management
+- API tokens are stored in environment variables or the system keychain
+- Secrets are never logged in plaintext
+- GitHub tokens are reused from `gh` CLI when possible
+- `.speexor/` directory is git-ignored (add to `.gitignore`)
+
+### Code Execution
+- AI agents generate and execute code in isolated git worktrees
+- Each agent runs in its own process/tmux session
+- Process runtime has resource limits (SIGTERM → SIGKILL after 5s)
+- Worktrees are cleaned up on session stop or package destroy
+
+### Network Security
+- Dashboard server listens on localhost by default
+- CORS is enabled (configurable in production)
+- No telemetry or tracking
+- **No mandatory cloud dependency** — core orchestration is fully local-first
+- **Known network exception:** The Extension Marketplace (`speexor ext search`, `speexor ext install`) makes outbound HTTPS calls to a public registry index (`marketplaceIndex` URL) to discover and download community extensions. This is optional: the marketplace can be fully disabled for air-gapped use by setting `extensions.marketplaceIndex: null` in config. User-configured LLM provider API calls and SCM (GitHub) API calls are the only other network dependencies — these are explicit user choices, not mandatory telemetry.
+
+### Data Protection
+- Session state stored in `.speexor/state.json` (local only)
+- Logs stored in `.speexor/logs/` (local only)
+- No data sent to external servers except configured AI providers and GitHub API
+- Users control which API endpoints are called
+
+### Supply Chain Security
+- All dependencies are pinned with exact versions
+- pnpm lockfile for deterministic installs
+- Regular dependency audits via `pnpm audit`
+- Minimal runtime dependencies (12 packages)
+
+## Security Checklist for Deployments
+
+- [ ] AI provider API keys stored in environment variables (not config files)
+- [ ] GitHub tokens use minimal scopes (repo, issues, pull requests)
+- [ ] Dashboard port not exposed to public internet
+- [ ] `.speexor/` directory added to `.gitignore`
+- [ ] Regular dependency updates (`pnpm audit`)
+- [ ] Agent output reviewed before auto-merge (auto-merge disabled by default)
+
+## Third-Party Security
+
+Speexor relies on:
+- **GitHub CLI (`gh`)** — user's existing authentication
+- **AI agent CLIs** — OpenCode, Claude Code, Aider, Codex — each with their own security models
+- **tmux** (Unix) / **Process** (Windows) — for runtime isolation
+
+Review the security documentation for each tool you use.
+
+## Incident Response
+
+1. **Detection** — Monitoring for unusual agent behavior or unauthorized access
+2. **Containment** — `speexor stop <session>` to halt affected agents
+3. **Analysis** — Review logs in `.speexor/logs/` and session state
+4. **Recovery** — Rotate affected credentials, clean up worktrees
+5. **Postmortem** — Document findings, update security practices

package/SUMMARY.md

@@ -3,19 +3,20 @@
 > Agent Orchestrator for multi-AI coding agent orchestration across repositories.
 
 ## Project Status
-- **Version:** 0.1.0 (pre-release)
+- **Version:** 0.2.0 (pre-release)
 - **License:** MIT
 - **Language:** TypeScript (ESM, ES2022)
 - **Node.js:** >= 18.0.0
+- **Test files:** 19 files, ~320 tests
 
 ## What It Does
 Speexor is an orchestration layer that spawns and manages multiple AI coding agents in parallel across one or more git repositories. Each agent runs in an isolated git worktree with its own runtime session, handles one task autonomously, and can automatically respond to CI failures and PR review comments.
 
 ## Scope
-- **Source files:** 31 TypeScript files (~2,430 lines)
-- **Plugins:** 10 implementations across 6 plugin slots
-- **CLI commands:** 6
-- **AI adapters:** OpenCode, Claude Code, Aider, Codex
+- **Source files:** 60+ TypeScript files (~5,200+ lines)
+- **Plugins:** 13+ implementations across 7 plugin slots
+- **CLI commands:** 14 (6 original + 8 new)
+- **AI adapters:** OpenCode, Claude Code, Aider, Codex (all with exponential retry)
 - **Runtime backends:** tmux (Unix), Process (Windows)
 
 ## Architecture Highlights
@@ -23,6 +24,13 @@ Speexor is an orchestration layer that spawns and manages multiple AI coding age
 - Agent-agnostic: no vendor lock to a single AI provider
 - Git-provider agnostic: GitHub as first implementation, interface open for GitLab/Gitea
 - Dashboard built-in: no external dependencies for monitoring
+- Recursive Task Decomposition (DAG-based planner)
+- Governance Engine (two-axis approval model)
+- Cost Tracking (per-provider/project/node with budget guard)
+- Extension Manager + Plugin SDK
+- Secrets Vault (OS-keychain backend)
+- Decision Quality Evaluation & Calibration
+- Interactive Dashboard v2 (Task Tree, Fleet, Approvals, Cost)
 
 ## Milestones
 
@@ -31,16 +39,31 @@ Speexor is an orchestration layer that spawns and manages multiple AI coding age
 | M0 — Foundation | Monorepo, core types, CLI skeleton, plugin contracts | ✅ Done |
 | M1 — Single Agent E2E | OpenCode adapter + tmux + worktree, E2E flow | ✅ Done |
 | M2 — GitHub Integration | Tracker + SCM + reaction engine | ✅ Done |
-| M3 — Multi-Agent | Claude Code, Aider, Codex adapters | ✅ Done |
+| M3 — Multi-Agent Adapters | Claude Code, Aider, Codex adapters | ✅ Done |
 | M4 — Dashboard MVP | REST API + HTML dashboard | ✅ Done |
-| M5 — Cost/Provider | Multi-provider routing config | 🔄 In Progress |
-| M6 — Polish & Docs | Documentation, examples, open-source readiness | 🔄 In Progress |
+| M5 — Cost Tracking & Budget Guard | Multi-provider routing config | ✅ Done |
+| M6 — Polish & Testing | Documentation, examples, open-source readiness | ✅ Done |
+| M7 — Task Graph Core & Decomposition | DAG planner, recursive decomposition | ✅ Done |
+| M8 — Parallel Scheduler | Resource-aware parallel execution | ✅ Done |
+| M9 — Governance & Approval | Two-axis approval model, risk policy | ✅ Done |
+| M10 — Extension Manager & SDK | Marketplace, manifest, permissions | ✅ Done |
+| M11 — Security & Secrets Vault | OS-keychain credential storage | ✅ Done |
+| M12 — Interactive Dashboard v2 | Task Tree, Fleet, Approvals, Cost panels | ✅ Done |
+| M22a — Critical Fixes (v5) | Edge case hardening, crash fixes | ✅ Done |
+| M22b — Major Fixes (v5) | Retry logic, race condition fixes | ✅ Done |
+| M22c — Documentation Consolidation | Cross-reference, glossary, API ref | ✅ Done |
+| M13 — Hardening & Cost Guard | Budget enforcement, guardrails, sandbox security, async store, live streaming | ✅ Done |
 
 ## Quick Links
 - [README](./README.md)
 - [Architecture](./ARCHITECTURE.md)
 - [Changelog](./CHANGELOG.md)
 - [Roadmap](./ROADMAP.md)
+- [Glossary](./GLOSSARY.md)
+- [API Reference](./API-REFERENCE.md)
+- [Benchmarks](./BENCHMARKS.md)
+- [Architecture Decisions](./docs/adr/)
+- [Security Defaults](./SECURITY-DEFAULTS.md)
 - [Contributing](./CONTRIBUTING.md)
 - [Security](./SECURITY.md)
 - [Testing](./TESTING.md)

package/TESTING.md

@@ -1,140 +1,140 @@
-# Testing Guide
-
-> Testing strategy and guidelines for Speexor — Agent Orchestrator.
-
-## Test Framework
-
-Speexor uses [Vitest](https://vitest.dev/) as the test framework with `@vitest/coverage-v8` for coverage reporting.
-
-```bash
-# Run all tests
-pnpm test
-
-# Watch mode
-pnpm test:watch
-
-# With coverage
-pnpm test:coverage
-```
-
-## Test Categories
-
-### Unit Tests
-Test individual modules in isolation:
-- **Core types** — Verify interface contracts and type guards
-- **Config validation** — Test Zod schemas with valid/invalid YAML
-- **Event bus** — Test emit/on/off/once behavior
-- **Plugin contracts** — Verify plugins implement required interfaces
-
-### Integration Tests
-Test module interactions:
-- **Lifecycle + plugins** — Verify plugin registration, agent spawn flow
-- **Config + lifecycle** — Verify config loading → lifecycle initialization
-- **Dashboard state** — Verify state mutations reflect correctly
-- **Session store** — Verify persistence round-trip
-
-### Plugin Tests
-Each plugin should be tested against its interface contract:
-- **Agent plugins** — Test spawn/sendInput/getStatus/kill lifecycle
-- **Runtime plugins** — Test createSession/destroySession flow
-- **Workspace plugin** — Test worktree lifecycle with mock git repo
-- **Tracker/SCM** — Test API calls (mock gh CLI)
-- **Notifier** — Test notification dispatch
-
-### E2E Tests (Future)
-Full end-to-end tests with real agent CLIs:
-- Requires installed agent CLI (opencode, claude-code, etc.)
-- Requires GitHub CLI authentication
-- Creates real worktrees and branches (clean up after)
-
-## Coverage Requirements
-
-| Category | Target |
-|----------|--------|
-| Core types & config | ≥90% |
-| CLI commands | ≥80% |
-| Plugin loader | ≥90% |
-| Agent adapters | ≥75% |
-| Runtime adapters | ≥80% |
-| Dashboard | ≥70% |
-| Reaction engine | ≥85% |
-| Session store | ≥90% |
-
-## Test Structure
-
-```
-tests/
-├── unit/
-│   ├── core/
-│   │   ├── config.test.ts
-│   │   ├── event-bus.test.ts
-│   │   └── lifecycle.test.ts
-│   ├── plugins/
-│   │   ├── opencode.test.ts
-│   │   ├── tmux.test.ts
-│   │   └── git-worktree.test.ts
-│   └── cli/
-│       └── commands.test.ts
-├── integration/
-│   ├── lifecycle-plugins.test.ts
-│   └── config-lifecycle.test.ts
-└── fixtures/
-    ├── valid-config.yaml
-    ├── invalid-config.yaml
-    └── mock-gh-responses/
-```
-
-## Writing Tests
-
-### Vitest Setup
-```typescript
-import { describe, it, expect, vi, beforeEach } from 'vitest'
-```
-
-### Example: Testing Config Validation
-```typescript
-import { validateConfig } from '../src/core/config.js'
-
-describe('Config Validation', () => {
-  it('accepts valid minimal config', () => {
-    const config = {
-      version: '1',
-      projects: [
-        {
-          name: 'test',
-          repository: 'https://github.com/user/repo',
-          provider: { primary: 'opencode' },
-        },
-      ],
-    }
-    expect(() => validateConfig(config)).not.toThrow()
-  })
-
-  it('rejects config without version', () => {
-    expect(() => validateConfig({ projects: [] })).toThrow()
-  })
-})
-```
-
-### Example: Testing Plugin Contract
-```typescript
-import { OpenCodeAgent } from '../src/plugins/agent/opencode.js'
-import { createEventBus } from '../src/core/event-bus.js'
-
-describe('OpenCodeAgent', () => {
-  it('implements AgentPlugin interface', () => {
-    const agent = new OpenCodeAgent()
-    expect(agent.name).toBe('opencode-agent')
-    expect(agent.type).toBe('agent')
-    expect(agent.spawn).toBeInstanceOf(Function)
-    expect(agent.kill).toBeInstanceOf(Function)
-  })
-})
-```
-
-## Mocking Guidelines
-
-- **gh CLI** — Use `vi.mock('node:child_process')` to mock execSync
-- **tmux** — Mock process execution, don't require tmux installation
-- **File system** — Use `vi.mock('node:fs')` for config/store tests
-- **Event bus** — Use real EventBus (not mocked) for integration tests
+# Testing Guide
+
+> Testing strategy and guidelines for Speexor — Agent Orchestrator.
+
+## Test Framework
+
+Speexor uses [Vitest](https://vitest.dev/) as the test framework with `@vitest/coverage-v8` for coverage reporting.
+
+```bash
+# Run all tests
+pnpm test
+
+# Watch mode
+pnpm test:watch
+
+# With coverage
+pnpm test:coverage
+```
+
+## Test Categories
+
+### Unit Tests
+Test individual modules in isolation:
+- **Core types** — Verify interface contracts and type guards
+- **Config validation** — Test Zod schemas with valid/invalid YAML
+- **Event bus** — Test emit/on/off/once behavior
+- **Plugin contracts** — Verify plugins implement required interfaces
+
+### Integration Tests
+Test module interactions:
+- **Lifecycle + plugins** — Verify plugin registration, agent spawn flow
+- **Config + lifecycle** — Verify config loading → lifecycle initialization
+- **Dashboard state** — Verify state mutations reflect correctly
+- **Session store** — Verify persistence round-trip
+
+### Plugin Tests
+Each plugin should be tested against its interface contract:
+- **Agent plugins** — Test spawn/sendInput/getStatus/kill lifecycle
+- **Runtime plugins** — Test createSession/destroySession flow
+- **Workspace plugin** — Test worktree lifecycle with mock git repo
+- **Tracker/SCM** — Test API calls (mock gh CLI)
+- **Notifier** — Test notification dispatch
+
+### E2E Tests (Future)
+Full end-to-end tests with real agent CLIs:
+- Requires installed agent CLI (opencode, claude-code, etc.)
+- Requires GitHub CLI authentication
+- Creates real worktrees and branches (clean up after)
+
+## Coverage Requirements
+
+| Category | Target |
+|----------|--------|
+| Core types & config | ≥90% |
+| CLI commands | ≥80% |
+| Plugin loader | ≥90% |
+| Agent adapters | ≥75% |
+| Runtime adapters | ≥80% |
+| Dashboard | ≥70% |
+| Reaction engine | ≥85% |
+| Session store | ≥90% |
+
+## Test Structure
+
+```
+tests/
+├── unit/
+│   ├── core/
+│   │   ├── config.test.ts
+│   │   ├── event-bus.test.ts
+│   │   └── lifecycle.test.ts
+│   ├── plugins/
+│   │   ├── opencode.test.ts
+│   │   ├── tmux.test.ts
+│   │   └── git-worktree.test.ts
+│   └── cli/
+│       └── commands.test.ts
+├── integration/
+│   ├── lifecycle-plugins.test.ts
+│   └── config-lifecycle.test.ts
+└── fixtures/
+    ├── valid-config.yaml
+    ├── invalid-config.yaml
+    └── mock-gh-responses/
+```
+
+## Writing Tests
+
+### Vitest Setup
+```typescript
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+```
+
+### Example: Testing Config Validation
+```typescript
+import { validateConfig } from '../src/core/config.js'
+
+describe('Config Validation', () => {
+  it('accepts valid minimal config', () => {
+    const config = {
+      version: '1',
+      projects: [
+        {
+          name: 'test',
+          repository: 'https://github.com/user/repo',
+          provider: { primary: 'opencode' },
+        },
+      ],
+    }
+    expect(() => validateConfig(config)).not.toThrow()
+  })
+
+  it('rejects config without version', () => {
+    expect(() => validateConfig({ projects: [] })).toThrow()
+  })
+})
+```
+
+### Example: Testing Plugin Contract
+```typescript
+import { OpenCodeAgent } from '../src/plugins/agent/opencode.js'
+import { createEventBus } from '../src/core/event-bus.js'
+
+describe('OpenCodeAgent', () => {
+  it('implements AgentPlugin interface', () => {
+    const agent = new OpenCodeAgent()
+    expect(agent.name).toBe('opencode-agent')
+    expect(agent.type).toBe('agent')
+    expect(agent.spawn).toBeInstanceOf(Function)
+    expect(agent.kill).toBeInstanceOf(Function)
+  })
+})
+```
+
+## Mocking Guidelines
+
+- **gh CLI** — Use `vi.mock('node:child_process')` to mock execSync
+- **tmux** — Mock process execution, don't require tmux installation
+- **File system** — Use `vi.mock('node:fs')` for config/store tests
+- **Event bus** — Use real EventBus (not mocked) for integration tests

package/dist/{agent-5D3BVWNK.js → agent-C64T66XT.js}

@@ -1,5 +1,5 @@
-import { loadConfig, SpeexorLifecycle } from './chunk-2F66BZYJ.js';
-import { loadAllPlugins } from './chunk-B7WLHC4W.js';
+import { loadConfig, SpeexorLifecycle } from './chunk-VEZQT5SX.js';
+import { loadAllPlugins } from './chunk-5OD5UWB5.js';
 import Debug from 'debug';
 
 var debug = Debug("speexor:agent");
@@ -33,5 +33,5 @@ async function agentSpawnCommand(options) {
 }
 
 export { agentSpawnCommand };
-//# sourceMappingURL=agent-5D3BVWNK.js.map
-//# sourceMappingURL=agent-5D3BVWNK.js.map
+//# sourceMappingURL=agent-C64T66XT.js.map
+//# sourceMappingURL=agent-C64T66XT.js.map

package/dist/agent-C64T66XT.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cli/agent.ts"],"names":[],"mappings":";;;;AAMA,IAAM,KAAA,GAAQ,MAAM,eAAe,CAAA;AAOnC,eAAsB,kBAAkB,OAAA,EAAuB;AAC7D,EAAA,MAAM,SAAS,UAAA,EAAW;AAC1B,EAAA,MAAM,SAAA,GAAY,IAAI,gBAAA,CAAiB,MAAM,CAAA;AAC7C,EAAA,MAAM,UAAU,UAAA,EAAW;AAE3B,EAAA,MAAM,UAAU,cAAA,EAAe;AAC/B,EAAA,KAAA,MAAW,UAAU,OAAA,EAAS;AAC5B,IAAA,SAAA,CAAU,eAAe,MAAM,CAAA;AAAA,EACjC;AAEA,EAAA,MAAM,OAAA,GAAU,MAAA,CAAO,QAAA,CAAS,CAAC,CAAA;AACjC,EAAA,IAAI,CAAC,OAAA,EAAS;AACZ,IAAA,MAAM,IAAI,MAAM,uBAAuB,CAAA;AAAA,EACzC;AAEA,EAAA,MAAM,IAAA,GAAkB;AAAA,IACtB,IAAI,OAAA,CAAQ,IAAA;AAAA,IACZ,OAAO,OAAA,CAAQ,IAAA;AAAA,IACf,WAAA,EAAa,CAAA,KAAA,EAAQ,OAAA,CAAQ,IAAI,CAAA,CAAA;AAAA,IACjC,YAAY,OAAA,CAAQ,UAAA;AAAA,IACpB,MAAA,EAAQ,CAAA,QAAA,EAAW,OAAA,CAAQ,IAAI,CAAA,CAAA;AAAA,IAC/B,QAAA,EAAW,OAAA,CAAQ,KAAA,IAA2B,OAAA,CAAQ,QAAA,CAAS;AAAA,GACjE;AAEA,EAAA,KAAA,CAAM,2BAA2B,IAAA,CAAK,EAAE,CAAA,OAAA,EAAU,IAAA,CAAK,QAAQ,CAAA,CAAE,CAAA;AAEjE,EAAA,MAAM,OAAA,GAAU,MAAM,SAAA,CAAU,UAAA,CAAW,IAAI,CAAA;AAC/C,EAAA,OAAA,CAAQ,GAAA,CAAI;AAAA,wBAAA,EAAwB,OAAA,CAAQ,EAAE,CAAA,CAAE,CAAA;AAChD,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,sBAAA,EAAkB,OAAA,CAAQ,QAAQ,CAAA,CAAE,CAAA;AAChD,EAAA,OAAA,CAAQ,GAAA,CAAI,CAAA,kBAAA,EAAc,IAAA,CAAK,EAAE;AAAA,CAAI,CAAA;AACvC","file":"agent-C64T66XT.js","sourcesContent":["import { loadConfig } from '../core/config.js'\r\nimport { SpeexorLifecycle } from '../core/lifecycle.js'\r\nimport { loadAllPlugins } from '../plugins/index.js'\r\nimport type { AgentTask, AgentProvider } from '../core/types.js'\r\nimport Debug from 'debug'\r\n\r\nconst debug = Debug('speexor:agent')\r\n\r\ninterface SpawnOptions {\r\n  task: string\r\n  agent: string\r\n}\r\n\r\nexport async function agentSpawnCommand(options: SpawnOptions) {\r\n  const config = loadConfig()\r\n  const lifecycle = new SpeexorLifecycle(config)\r\n  await lifecycle.initialize()\r\n\r\n  const plugins = loadAllPlugins()\r\n  for (const plugin of plugins) {\r\n    lifecycle.registerPlugin(plugin)\r\n  }\r\n\r\n  const project = config.projects[0]\r\n  if (!project) {\r\n    throw new Error('No project configured')\r\n  }\r\n\r\n  const task: AgentTask = {\r\n    id: options.task,\r\n    title: options.task,\r\n    description: `Task ${options.task}`,\r\n    repository: project.repository,\r\n    branch: `speexor/${options.task}`,\r\n    provider: (options.agent as AgentProvider) || project.provider.primary,\r\n  }\r\n\r\n  debug(`Spawning agent for task ${task.id} using ${task.provider}`)\r\n\r\n  const session = await lifecycle.spawnAgent(task)\r\n  console.log(`\\n  ✅ Agent spawned: ${session.id}`)\r\n  console.log(`  🤖 Provider: ${session.provider}`)\r\n  console.log(`  📋 Task: ${task.id}\\n`)\r\n}\r\n"]}