super-subagents 1.1.2 → 1.3.4

package/.github/workflows/publish.yml

@@ -29,4 +29,4 @@ jobs:
         run: npm run build
 
       - name: Publish
-        run: npm publish --provenance --access public
+        run: npm publish --access public

package/.github/workflows/version-bump.yml

@@ -27,11 +27,12 @@ jobs:
 
       - name: Determine bump type
         id: bump
+        env:
+          COMMIT_MSG: ${{ github.event.head_commit.message }}
         run: |
-          MSG="${{ github.event.head_commit.message }}"
-          if echo "$MSG" | grep -qiE '^breaking|^major'; then
+          if echo "$COMMIT_MSG" | head -1 | grep -qiE '^breaking|^major'; then
             echo "type=major" >> "$GITHUB_OUTPUT"
-          elif echo "$MSG" | grep -qiE '^feat'; then
+          elif echo "$COMMIT_MSG" | head -1 | grep -qiE '^feat'; then
             echo "type=minor" >> "$GITHUB_OUTPUT"
           else
             echo "type=patch" >> "$GITHUB_OUTPUT"

package/CLAUDE.md

@@ -5,63 +5,195 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ## Build & Development Commands
 
 ```bash
-npm install          # Install dependencies
-npm run build        # Compile TypeScript to build/
+npm install          # Install dependencies (copilot-sdk is a local file dep at ./copilot-sdk/nodejs)
+npm run build        # Compile TypeScript to build/ (also need to copy *.mdx: cp src/templates/*.mdx build/templates/)
 npm run dev          # Watch mode with tsx (auto-reload)
-npm start            # Run compiled server
+npm start            # Run compiled server (requires build first)
 npm run clean        # Remove build directory
 ```
 
+**Build note:** `tsc` only compiles `.ts` files. After `npm run build`, you must also run `cp src/templates/*.mdx build/templates/` to copy template files. The `@github/copilot-sdk` is a local dependency (`file:./copilot-sdk/nodejs`). If `copilot-sdk/nodejs/dist/` is missing, build it first: `cd copilot-sdk/nodejs && npm install && npm run build`.
+
+**Known type errors:** There are pre-existing `TS2345` errors in `sdk-spawner.ts` (lines 42/51, `task.cwd` is `string | undefined` vs `string`) and some type-only import mismatches against the SDK. These are safe at runtime since type imports are erased. Use `npx tsc --noEmitOnError false` if needed to emit JS despite type errors.
+
 ## Architecture Overview
 
-This is an MCP (Model Context Protocol) server that spawns GitHub Copilot CLI agents as background tasks. It wraps the Copilot CLI (`/opt/homebrew/bin/copilot` by default) with task management, dependency chains, and automatic rate-limit retry.
+This is an MCP server that manages GitHub Copilot agents as autonomous SDK sessions. It provides task orchestration, multi-account PAT rotation for rate limit recovery, dependency chains, and session lifecycle management over the MCP protocol.
+
+The server exposes 4 MCP tools, MCP resources for task state, and MCP task lifecycle endpoints. Clients (Claude Code, VS Code, etc.) interact exclusively through the MCP protocol over stdio.
+
+### Directory Structure
+
+```
+src/
+├── index.ts                     # MCP server setup, tool/resource/task handlers, lifecycle wiring (649 lines)
+├── types.ts                     # All shared types: TaskState, TaskStatus, SpawnOptions, SessionMetrics, etc. (284 lines)
+├── models.ts                    # Model registry (sonnet/opus/haiku), ENABLE_OPUS gating (24 lines)
+├── config/
+│   └── timeouts.ts              # Timeout constants with env var overrides (17 lines)
+├── services/
+│   ├── sdk-spawner.ts           # Top-level task spawning, error classification, rate limit handling (494 lines)
+│   ├── sdk-client-manager.ts    # CopilotClient pool per workspace+token, session create/resume/destroy (408 lines)
+│   ├── sdk-session-adapter.ts   # Binds SDK sessions to tasks, handles events, rotation, metrics (1,104 lines)
+│   ├── session-hooks.ts         # SDK SessionHooks for lifecycle (start/end/error/tool) logging (171 lines)
+│   ├── task-manager.ts          # Central state machine: lifecycle, dependencies, persistence, cleanup (830 lines)
+│   ├── task-persistence.ts      # Atomic JSON persistence to ~/.super-agents/{hash}.json (176 lines)
+│   ├── task-status-mapper.ts    # Maps 8-state internal model → MCP 4-state model + status messages (288 lines)
+│   ├── account-manager.ts       # Multi-account PAT rotation (round-robin, cooldown, failover) (302 lines)
+│   ├── question-registry.ts     # SDK ask_user → MCP bridge: stores pending questions, resolves answers (336 lines)
+│   ├── retry-queue.ts           # Exponential backoff for rate-limited tasks (5m → 2h) (232 lines)
+│   ├── progress-registry.ts     # Throttled MCP progress notifications per task (123 lines)
+│   ├── subscription-registry.ts # MCP resource subscription tracking (task:/// URIs) (33 lines)
+│   ├── client-context.ts        # Stores client workspace roots from MCP initialization (49 lines)
+│   └── output-file.ts           # Live output files at {cwd}/.super-agents/{taskId}.output (97 lines)
+├── tools/
+│   ├── spawn-task.ts            # spawn_task: create new agent tasks with template+model selection (159 lines)
+│   ├── cancel-task.ts           # cancel_task: cancel one or all tasks (supports "all" keyword) (181 lines)
+│   ├── send-message.ts          # send_message: send follow-up messages to existing sessions (178 lines)
+│   └── answer-question.ts       # answer_question: respond to SDK ask_user questions (140 lines)
+├── templates/
+│   ├── index.ts                 # Template registry and {{user_prompt}} substitution (37 lines)
+│   ├── super-coder.mdx          # Coding: "think 10 times, write once" — search→think→plan→implement→verify (518 lines)
+│   ├── super-planner.mdx        # Planning: evidence-based design with codebase exploration mandate (557 lines)
+│   ├── super-researcher.mdx     # Research: multi-angle investigation with source authority ranking (393 lines)
+│   ├── super-tester.mdx         # Testing: "test like a user, not a developer" — E2E > integration > unit (687 lines)
+│   ├── super-questioner.mdx     # Forces ask_user before proceeding (13 lines)
+│   └── super-arabic.mdx         # Arabic-language agent (8 lines)
+└── utils/
+    ├── sanitize.ts              # Zod schemas for tool input validation (20 lines)
+    ├── format.ts                # MCP response formatting: mcpText, formatError, formatTable (38 lines)
+    └── task-id-generator.ts     # Human-readable IDs: brave-tiger-42 (25 lines)
+```
+
+### Request Flow (spawn_task)
+
+1. `spawn-task.ts:85` validates input via Zod, applies template from `templates/index.ts:25`
+2. `sdk-spawner.ts:67` creates `TaskState` via `taskManager.createTask()`, then calls `runSDKSession()` via `setImmediate`
+3. `sdk-client-manager.ts` gets/creates a `CopilotClient` for the workspace+token, creates a `CopilotSession` with hooks
+4. `sdk-session-adapter.ts` binds the session to the task, subscribing to all SDK `SessionEvent`s
+5. `session.sendAndWait({ prompt }, timeout)` runs the prompt; adapter handles events (output, errors, tool calls, usage, subagents)
+6. On completion/error, `task-manager.ts` transitions state via `updateTask()` and triggers side effects
 
-### Core Components
+### Key Architectural Patterns
 
-**Entry Point** (`src/index.ts`): Sets up MCP server, registers all tools, and wires up task manager callbacks for retry and dependency execution.
+**Singleton services:** Most services export a singleton instance (`taskManager`, `sdkClientManager`, `sdkSessionAdapter`, `accountManager`, `questionRegistry`, `progressRegistry`, `subscriptionRegistry`, `clientContext`). Import them directly; don't instantiate.
+
+**Session binding:** `sdk-session-adapter.ts` maintains a `SessionBinding` per task that subscribes to SDK `SessionEvent`s. On rotation, it unbinds the old session and rebinds a new one. The binding tracks rotation attempts, timeout state, and whether rotation is in progress.
+
+**TERMINAL_STATUSES:** Exported from `task-manager.ts` as a `Set` containing `COMPLETED`, `FAILED`, `CANCELLED`, `TIMED_OUT`. `RATE_LIMITED` is intentionally NOT terminal — the retry system can still update these tasks. Always import from `task-manager.ts`; don't define locally.
+
+**State transitions via updateTask():** Always use `taskManager.updateTask()` to change task state — never mutate `task.status` directly. `updateTask()` triggers: output file finalization, persistence scheduling, dependency resolution (`processWaitingTasks`), status change callbacks.
+
+**Tool metrics tracking:** Handled exclusively by `sdk-session-adapter.ts` using `toolCallId`-based matching. `session-hooks.ts` only logs tool events; it does NOT track metrics (avoids duplicate writes to `task.sessionMetrics.toolMetrics`).
+
+**Terminal state guards:** Both `sdk-session-adapter.ts` and `sdk-spawner.ts` check `isTerminalStatus()` before updating task state. This prevents race conditions where the adapter handles an error event and the spawner's `sendAndWait` also throws.
+
+### Task Lifecycle
+
+```
+PENDING → RUNNING → COMPLETED
+                  → FAILED
+                  → CANCELLED (via cancel_task)
+                  → TIMED_OUT (hard timeout or stall)
+                  → RATE_LIMITED → (retry) → PENDING → ...
+PENDING → WAITING (has unmet dependencies) → PENDING → RUNNING → ...
+```
 
-**Task Manager** (`src/services/task-manager.ts`): Central state machine managing all tasks. Handles:
-- Task lifecycle (pending → waiting → running → completed/failed/cancelled/rate_limited/timed_out)
-- Dependency resolution via `areDependenciesSatisfied()` and `processWaitingTasks()`
-- Persistence scheduling with debouncing
-- Auto-cleanup of expired tasks (1 hour TTL)
+### Multi-Account Rotation
 
-**Process Spawner** (`src/services/process-spawner.ts`): Executes Copilot CLI via `execa`. Builds command args, captures stdout/stderr, detects rate limits, and handles timeouts.
+When a rate limit (429) or server error (5xx) occurs:
 
-**Persistence** (`src/services/task-persistence.ts`): Tasks persist to `~/.super-agents/{md5(cwd)}.json`. Uses atomic writes (write temp → rename).
+1. **Mid-session (adapter):** `sdk-session-adapter.ts` detects error event → calls `attemptRotationAndResume()` → rotates token via `accountManager` → health-checks new account → resumes session with `session.sendAndWait({ prompt: 'continue' })`
+2. **Post-session (spawner):** `sdk-spawner.ts:278` catches `sendAndWait` exception → extracts status code → tries `rotateOnError()` → retries with new session
+3. **All exhausted:** Falls back to exponential backoff via `retry-queue.ts` (5m → 10m → 20m → 40m → 1h → 2h, max 6 retries)
 
-**Retry Queue** (`src/services/retry-queue.ts`): Detects rate-limit errors via regex patterns, calculates exponential backoff (5m → 10m → 20m → 40m → 1h → 2h), and extracts wait times from error messages.
+Tokens configured via env vars. Failed tokens enter 60s cooldown before reuse.
 
-### Tool Handlers
+### SDK Question/Answer Flow
 
-Each tool in `src/tools/` exports:
-- A tool definition object (`{name, description, inputSchema}`)
-- A handler function that validates input via Zod schemas from `src/utils/sanitize.ts`
+When the Copilot agent calls `ask_user`:
+1. `sdk-client-manager.ts` `onUserInputRequest` handler fires
+2. `question-registry.ts` stores the question, updates `task.pendingQuestion`, returns a Promise
+3. MCP client sees pending question via resource `task:///{id}` or MCP notification
+4. Client calls `answer_question` tool → registry resolves Promise → SDK resumes
 
-### Templates
+Questions time out after 30 minutes.
 
-Task templates in `src/templates/*.mdx` wrap user prompts with specialized instructions. The `applyTemplate()` function replaces `{{user_prompt}}` placeholder or appends if not found.
+### SDK Interface Notes
 
-### Key Types
+The `@github/copilot-sdk` (local at `./copilot-sdk/nodejs`) exports:
+- **Values (runtime):** `CopilotClient`, `CopilotSession`, `defineTool`
+- **Types (erased):** `SessionHooks`, `SessionConfig`, `SessionEvent`, `MessageOptions`, `UserInputRequest`, `UserInputResponse`, and all hook input/output types
 
-- `TaskStatus` enum: `pending`, `waiting`, `running`, `completed`, `failed`, `cancelled`, `rate_limited`, `timed_out`
-- `TaskState`: Full task object with output buffer, retry info, dependencies, labels
-- `SpawnOptions`: Input for creating tasks
+Key SDK method signatures:
+- `session.sendAndWait(options: MessageOptions, timeout?: number)` — `MessageOptions` requires `{ prompt: string }`, NOT a plain string
+- `session.abort()` — Cancels session
+- `session.destroy()` — Tears down session completely
+- `SessionHooks` uses single handler functions (`onSessionStart`, `onSessionEnd`, `onErrorOccurred`, `onPreToolUse`, `onPostToolUse`), NOT arrays
+- `PreToolUseHookOutput` uses `permissionDecision: 'allow' | 'deny'`, NOT `decision`
+- `PostToolUseHookInput.toolResult.resultType` is `'success' | 'failure'` (camelCase, lowercase)
+- `UsageMetricsTracker` is NOT exported by the SDK — do not try to import it as a value
 
-### Task IDs
+## Key Types
 
-Human-readable IDs like `brave-tiger-42` generated via `unique-names-generator`. Normalized to lowercase for lookups.
+- `TaskStatus` enum (8 states): `pending`, `waiting`, `running`, `completed`, `failed`, `cancelled`, `rate_limited`, `timed_out`
+- `TaskState`: Full task state including `session`, `sessionMetrics`, `failureContext`, `pendingQuestion`, `outputFilePath`
+- `SpawnOptions`: Input for `spawnCopilotTask()` — prompt, model, cwd, timeout, dependsOn, labels, etc.
+- `SessionMetrics`: Aggregated metrics per session — quotas, tool metrics, subagents, turn count, token usage
+- `FailureContext`: Structured error from SDK — errorType, statusCode, errorContext, recoverable flag
+- `PendingQuestion`: Question from ask_user — question text, choices, allowFreeform, sessionId
+- `ToolContext`: MCP request context with `progressToken` and `sendNotification`
 
 ## Environment Variables
 
 | Variable | Default | Purpose |
 |----------|---------|---------|
-| `COPILOT_PATH` | `/opt/homebrew/bin/copilot` | Path to Copilot CLI executable |
-| `ENABLE_OPUS` | `false` | Allow opus model (cost control) |
-| `ENABLE_STREAMING` | `false` | Enable experimental `stream_output` tool |
+| `GITHUB_PAT_TOKENS` | — | Comma-separated PAT tokens for multi-account rotation |
+| `GITHUB_PAT_TOKEN_1`..`_N` | — | Numbered PAT tokens (alternative to comma-separated) |
+| `GH_PAT_TOKEN` | — | Fallback PAT token(s), comma-separated |
+| `GITHUB_TOKEN` / `GH_TOKEN` | — | Single token fallback |
+| `ENABLE_OPUS` | `false` | Allow claude-opus-4.5 model (cost control) |
+| `MCP_TASK_TIMEOUT_MS` | `1800000` (30m) | Default task timeout |
+| `MCP_TASK_TIMEOUT_MIN_MS` | `1000` | Minimum allowed timeout |
+| `MCP_TASK_TIMEOUT_MAX_MS` | `3600000` (1h) | Maximum allowed timeout |
+| `MCP_TASK_STALL_WARN_MS` | `300000` (5m) | Stall warning threshold |
+
+## MCP Resources
+
+Tasks are exposed as MCP resources with URI scheme `task:///`:
+- `system:///status` — Account stats, task counts, SDK info
+- `task:///all` — List all tasks with status, progress, pending questions
+- `task:///{taskId}` — Full task details, output, metrics
+- `task:///{taskId}/session` — Execution log with tool calls
+
+Clients can subscribe to resource URIs for real-time change notifications (debounced to max 1/sec per task).
 
 ## Adding New Tools
 
-1. Create `src/tools/new-tool.ts` with tool definition and handler
-2. Import and add to `tools` array in `src/index.ts`
-3. Add case to switch statement in `CallToolRequestSchema` handler
+1. Create `src/tools/new-tool.ts` with:
+   - A Zod schema for input validation
+   - A tool definition object (`{ name, description, inputSchema }`)
+   - A handler function `handleNewTool(args, context)`
+2. Import and add to `tools` array and switch statement in `src/index.ts:166`
+
+## Adding New Templates
+
+1. Create `src/templates/super-newtype.mdx` with `{{user_prompt}}` placeholder
+2. Add entry to `TASK_TYPES` in `src/templates/index.ts:7`
+3. Rebuild (`npm run build && cp src/templates/*.mdx build/templates/`)
+
+## Common Pitfalls
+
+- **Never mutate task state directly.** Always go through `taskManager.updateTask()`. Direct mutation skips persistence, output finalization, and dependency processing.
+- **TERMINAL_STATUSES is a Set, not an array.** Use `.has()`, not `.includes()`. Import it from `task-manager.ts`.
+- **RATE_LIMITED is not terminal.** The retry system needs to update these tasks. Don't treat it as a final state.
+- **Session cleanup on state transitions.** When a task leaves RUNNING (to RATE_LIMITED, FAILED, etc.), set `session: undefined` in the update. `updateTask()` handles this for terminal statuses and RATE_LIMITED.
+- **Check terminal state before updating.** Both `sdk-session-adapter.ts` and `sdk-spawner.ts` must check `isTerminalStatus()` before writing — otherwise one overwrites the other's state transition.
+- **Rotation attempts must be incremented.** Both reactive (error-triggered) and proactive (low-quota) rotation paths must increment `binding.rotationAttempts` to respect `maxRotationAttempts`.
+- **Health check sessions must be cleaned up.** `sdk-session-adapter.ts` creates temporary sessions for health checks — destroy via `sdkClientManager.destroySession()`.
+- **`handleEvent` in sdk-session-adapter is async.** Event listener callbacks must handle the returned promise with `.catch()`.
+- **Tool metrics tracked by sdk-session-adapter only.** Uses `toolCallId`-based matching for accuracy. Don't add metrics tracking to `session-hooks.ts`.
+- **`sendAndWait` takes `MessageOptions`, not a string.** Use `session.sendAndWait({ prompt: 'text' })`, never `session.sendAndWait('text')`.
+- **`SessionHooks` uses single handlers.** Use `onPreToolUse: async (input) => { ... }`, not `preToolUse: [async (input) => { ... }]`.
+- **Copy MDX files after build.** `tsc` doesn't copy `.mdx` files. Run `cp src/templates/*.mdx build/templates/` after each build.
+- **Resumed sessions must be tracked.** When calling `sdkClientManager.resumeSession()`, the session is added to `entry.sessions` Map so it can be found for abort/destroy.

package/README.md

@@ -1,129 +1,245 @@
-# Super Agents MCP Server
+# Super Subagents
 
-MCP server that spawns GitHub Copilot CLI agents as background tasks with human-readable IDs, dependency chains, and automatic rate-limit retry.
+Run multiple AI agents in parallel from a single MCP client. Spawn autonomous GitHub Copilot sessions as background tasks — each one gets its own workspace, tools, and execution context. Your main session stays unblocked while agents code, plan, research, and test simultaneously.
 
-## Quick Start
+## Why
 
-Install via install-mcp:
-```bash
-npx install-mcp super-subagents --client claude-desktop
+AI coding assistants work one task at a time. You ask it to refactor a module, and you wait. Then you ask it to write tests, and you wait again. Then you ask it to update the docs.
+
+Super Subagents changes this. From your MCP client (Claude Code, VS Code, etc.), you spawn tasks that run as independent Copilot SDK sessions in the background:
+
+```
+You (main session):  "Spawn three tasks: refactor auth, write API tests, update the migration guide"
+
+→ brave-tiger-42:    Refactoring auth module...          [running]
+→ calm-falcon-17:    Writing API integration tests...    [running]
+→ swift-panda-88:    Updating migration guide...         [running]
+
+You:                 Continue working on other things — or spawn more tasks.
 ```
 
-Manual build:
+Each agent runs with full tool access (file read/write, terminal, search) in its own isolated session. When it finishes, you get notified. If it hits a rate limit, it rotates to another GitHub account automatically.
+
+## Quick Start
+
+**Option 1: Auto-install**
 ```bash
-npm install && npm run build
+npx @automcp/cli install super-subagents --client claude-desktop
 ```
 
+**Option 2: Manual config**
+
+Add to your MCP client config (e.g., `~/Library/Application Support/Claude/claude_desktop_config.json`):
+
 ```json
 {
   "mcpServers": {
     "super-agents": {
-      "command": "node",
-      "args": ["/path/to/copilot-agents/build/index.js"]
+      "command": "npx",
+      "args": ["-y", "super-subagents"],
+      "env": {
+        "GITHUB_PAT_TOKENS": "ghp_token1,ghp_token2"
+      }
     }
   }
 }
 ```
 
+No build step required — `npx` runs the package directly.
+
+## How It Works
+
+Super Subagents is an MCP server. Your MCP client connects to it over stdio and gets 4 tools and a set of resources for monitoring.
+
+**Spawning a task** creates an autonomous Copilot SDK session that runs in the background. The session has full access to the filesystem, terminal, and all tools the Copilot agent normally has. Your prompt is the agent's only context — it can't see your conversation history.
+
+**Monitoring** happens via MCP resources (not polling). Subscribe to `task:///{id}` for real-time updates, or read `task:///all` to see everything at once. Each task also writes a live output file you can `tail -f`.
+
+**Rate limits** are handled automatically. With multiple PAT tokens configured, the server rotates to the next account when one gets rate-limited. If all accounts are exhausted, tasks enter exponential backoff and retry automatically.
+
 ## Tools
 
-| Tool | Description |
+| Tool | What it does |
 |------|-------------|
-| `spawn_task` | Create a task. Returns `task_id` for tracking. |
-| `batch_spawn` | Create multiple tasks with dependency chains (max 20). |
-| `get_status` | Check task status. Supports batch checking with array. |
-| `list_tasks` | List all tasks. Filter by `status` or `label`. |
-| `resume_task` | Resume interrupted session by `session_id`. |
-| `retry_task` | Immediately retry a rate-limited task. |
-| `cancel_task` | Kill a running/pending task (SIGTERM). |
-| `recover_task` | Recover a timed_out task (resume if session is available). |
-| `force_start` | Start a waiting task, bypassing dependencies. |
-| `clear_tasks` | Delete all tasks for workspace. Requires `confirm: true`. |
-| `stream_output` | *(experimental)* Get incremental output with offset. Requires `ENABLE_STREAMING=true`. |
+| `spawn_task` | Create a new autonomous agent task. Returns a `task_id`. |
+| `send_message` | Send a follow-up message to a completed/failed task's session. |
+| `cancel_task` | Cancel one task, multiple tasks, or all tasks. |
+| `answer_question` | Respond when an agent asks a question via `ask_user`. |
+
+## Resources
+
+All status and monitoring is done through MCP resources:
+
+| Resource URI | Content |
+|-------------|---------|
+| `system:///status` | Account stats, task counts, SDK health |
+| `task:///all` | All tasks with status, progress, pending questions |
+| `task:///{id}` | Full task details: output, metrics, config |
+| `task:///{id}/session` | Execution log: turns, tool calls, durations |
 
-## Task Statuses
+## Agent Templates
 
-`pending` → `waiting` → `running` → `completed` | `failed` | `cancelled` | `rate_limited` | `timed_out`
+Templates wrap your prompt with specialized system instructions. The agent sees the template + your prompt, not your conversation.
 
-## Features
+| Template | Personality | Best for |
+|----------|------------|----------|
+| `super-coder` | "Think 10 times, write once." Searches the codebase before touching anything. Verifies after every change. | Implementation, bug fixes, refactoring |
+| `super-planner` | "Plan with evidence, not assumptions." Explores the codebase first, then designs atomic tasks with dependency graphs. | Architecture, design docs, task breakdown |
+| `super-researcher` | "Find truth, not confirmation." Multi-angle investigation with source authority ranking. | Codebase exploration, technical questions |
+| `super-tester` | "Test like a user, not a developer." E2E first, then integration, then unit. Collects evidence. | QA, test writing, verification |
+| `super-questioner` | Always asks a clarifying question before starting work. | Tasks with ambiguous requirements |
+| `super-arabic` | Responds entirely in Arabic. | Arabic-language tasks |
 
-### Dependencies
 ```json
-{ "prompt": "Deploy", "depends_on": ["build-task-id", "test-task-id"] }
+{ "prompt": "Fix the null check in auth.ts line 45", "task_type": "super-coder" }
 ```
-Task waits until all dependencies complete. Use `force_start` to bypass.
 
-### Labels
-```json
-{ "prompt": "Build API", "labels": ["backend", "urgent"] }
+Without a `task_type`, the agent gets your raw prompt with no system instructions.
+
+## Models
+
+| Model | When to use |
+|-------|------------|
+| `claude-sonnet-4.5` | Default. Best balance of speed and capability. |
+| `claude-haiku-4.5` | Simple tasks, quick iterations. |
+| `claude-opus-4.5` | Complex reasoning, large refactors. Requires `ENABLE_OPUS=true`. |
+
+## Multi-Account Rotation
+
+Configure multiple GitHub PAT tokens. When one account hits a rate limit (429) or server error (5xx), the server rotates to the next automatically — mid-session, without losing progress.
+
+```bash
+# Comma-separated (recommended)
+GITHUB_PAT_TOKENS=ghp_token1,ghp_token2,ghp_token3
+
+# Or numbered
+GITHUB_PAT_TOKEN_1=ghp_token1
+GITHUB_PAT_TOKEN_2=ghp_token2
+
+# Or single token
+GITHUB_TOKEN=ghp_token
 ```
-Filter with `list_tasks({ "label": "backend" })`.
 
-### Batch Spawn
+Failed tokens enter a 60-second cooldown before reuse. If all tokens are exhausted, tasks enter exponential backoff (5m, 10m, 20m, 40m, 1h, 2h — max 6 retries).
+
+## Task Dependencies
+
+Tasks can wait for other tasks:
+
 ```json
 {
-  "tasks": [
-    { "id": "build", "prompt": "Build project" },
-    { "id": "test", "prompt": "Run tests", "depends_on": ["build"] },
-    { "id": "deploy", "prompt": "Deploy", "depends_on": ["test"] }
-  ]
+  "prompt": "Deploy the service",
+  "depends_on": ["build-task-id", "test-task-id"]
 }
 ```
-Local `id` fields map to real `task_id` in response.
 
-### Task Templates
+The task stays in `waiting` status until all dependencies complete, then auto-starts. Circular dependencies are detected and rejected.
+
+## Question Handling
+
+When a Copilot agent calls `ask_user`, the task pauses and surfaces the question through MCP notifications and resources.
 
-| Template | Use Case |
-|----------|----------|
-| `super-coder` | Implementation, bug fixes, refactoring |
-| `super-planner` | Architecture, design decisions |
-| `super-researcher` | Codebase exploration, investigation |
-| `super-tester` | Writing tests, QA verification |
+```json
+// Answer by choice number (1-indexed)
+{ "task_id": "brave-tiger-42", "answer": "2" }
 
-### Models
-`claude-sonnet-4.5` (default), `claude-haiku-4.5`. Opus blocked by default (set `ENABLE_OPUS=true` to allow).
+// Or free-form text
+{ "task_id": "brave-tiger-42", "answer": "CUSTOM: Use TypeScript instead" }
+```
 
-### Timeout
-Default: 30 min (1800000ms). Max: 1 hour. Tasks exceeding timeout get `timed_out` status.
-Configurable via `MCP_TASK_TIMEOUT_MS`, `MCP_TASK_TIMEOUT_MIN_MS`, and `MCP_TASK_TIMEOUT_MAX_MS`. Prefer the default unless you have a clear reason to override.
-Stall warnings are based on `MCP_TASK_STALL_WARN_MS`. Timed out tasks may include a reason and can be recovered via `recover_task` or `resume_task` when a session is available.
+Pending questions appear in `task:///all` and on the individual task resource. Questions time out after 30 minutes.
 
-### Rate Limit Auto-Retry
-Rate-limited tasks auto-retry with exponential backoff (5m → 10m → 20m → 40m → 1h → 2h). Max 6 retries.
+## Session Continuation
 
-### Persistence
-Tasks persist to `~/.super-agents/{md5(cwd)}.json`. Survives server restarts.
+Send follow-up messages to completed or failed tasks:
 
-### Output Streaming (Experimental)
-Requires `ENABLE_STREAMING=true`. Disabled by default.
 ```json
-// First call
-{ "task_id": "brave-tiger-42", "offset": 0 }
-// Response: { "lines": [...], "next_offset": 50, "has_more": true }
+// Default: "continue"
+{ "task_id": "brave-tiger-42" }
 
-// Subsequent calls
-{ "task_id": "brave-tiger-42", "offset": 50 }
+// With a specific message
+{ "task_id": "brave-tiger-42", "message": "Now add unit tests for the changes you made" }
 ```
-Use `next_offset` from response to get new lines without re-fetching.
 
-### Polling Backoff
-Response includes `retry_after_seconds` (30s → 60s → 120s → 180s) to prevent excessive polling.
+This creates a new task that resumes the same Copilot session, so the agent retains full context of what it did.
+
+## Live Output Files
+
+Every task writes a live output file at `{cwd}/.super-agents/{task-id}.output`:
+
+```bash
+tail -f .super-agents/brave-tiger-42.output    # Follow live
+tail -20 .super-agents/brave-tiger-42.output   # Last 20 lines
+cat .super-agents/brave-tiger-42.output        # Full output
+```
 
-## Environment
+Output files include a header (task ID, start time, working directory), all tool calls with durations, reasoning traces, usage metrics, and a footer (completion time, final status).
+
+## Task Lifecycle
+
+```
+pending → running → completed
+                  → failed
+                  → cancelled
+                  → timed_out
+                  → rate_limited → (auto-retry) → pending → running → ...
+
+pending → waiting (dependencies) → pending → running → ...
+```
+
+Eight internal states map to four MCP states (`working`, `completed`, `failed`, `cancelled`) for clients that use MCP task primitives.
+
+## Persistence
+
+Tasks persist to `~/.super-agents/{md5(cwd)}.json`. Survives server restarts. Rate-limited tasks auto-retry on reconnect. Output files persist in `{cwd}/.super-agents/` for post-hoc review.
+
+## Environment Variables
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `COPILOT_PATH` | `/opt/homebrew/bin/copilot` | Copilot CLI path |
-| `ENABLE_OPUS` | `false` | Allow opus model (cost control) |
-| `ENABLE_STREAMING` | `false` | Enable experimental `stream_output` tool |
-| `MCP_TASK_TIMEOUT_MS` | `1800000` | Default task timeout (ms) |
-| `MCP_TASK_TIMEOUT_MIN_MS` | `1000` | Minimum allowed task timeout (ms) |
-| `MCP_TASK_TIMEOUT_MAX_MS` | `3600000` | Maximum allowed task timeout (ms) |
-| `MCP_TASK_STALL_WARN_MS` | `300000` | No-output stall warning threshold (ms) |
-| `MCP_COPILOT_SWITCH_TIMEOUT_MS` | `120000` | Timeout for copilot-switch command (ms) |
-| `MCP_COPILOT_SWITCH_LOCK_STALE_MS` | `150000` | Stale lock threshold for copilot-switch (ms) |
-| `MCP_COPILOT_SWITCH_LOCK_TIMEOUT_MS` | `150000` | Wait timeout for copilot-switch lock (ms) |
-| `MCP_COPILOT_SWITCH_LOCK_POLL_MS` | `500` | Lock poll interval for copilot-switch (ms) |
+| `GITHUB_PAT_TOKENS` | — | Comma-separated PAT tokens for multi-account rotation |
+| `GITHUB_PAT_TOKEN_1`..`_N` | — | Numbered PAT tokens |
+| `GH_PAT_TOKEN` | — | Fallback PAT token(s), comma-separated |
+| `GITHUB_TOKEN` / `GH_TOKEN` | — | Single token fallback |
+| `ENABLE_OPUS` | `false` | Allow claude-opus-4.5 model |
+| `MCP_TASK_TIMEOUT_MS` | `1800000` | Default task timeout (30 min) |
+| `MCP_TASK_TIMEOUT_MAX_MS` | `3600000` | Maximum allowed timeout (1 hour) |
+| `MCP_TASK_STALL_WARN_MS` | `300000` | No-output warning threshold (5 min) |
+
+## Example: Parallel Feature Development
+
+```
+1. spawn_task({
+     prompt: "Implement the /api/users endpoint. Read the OpenAPI spec at /docs/api.yaml for the schema...",
+     task_type: "super-coder",
+     labels: ["backend", "users-feature"]
+   })
+   → Task: brave-tiger-42
+
+2. spawn_task({
+     prompt: "Write E2E tests for the /api/users endpoint using the test patterns in /tests/...",
+     task_type: "super-tester",
+     depends_on: ["brave-tiger-42"],
+     labels: ["testing", "users-feature"]
+   })
+   → Task: calm-falcon-17 (waiting for brave-tiger-42)
+
+3. spawn_task({
+     prompt: "Research best practices for user data pagination. Compare cursor vs offset...",
+     task_type: "super-researcher",
+     labels: ["research", "users-feature"]
+   })
+   → Task: swift-panda-88 (starts immediately, runs in parallel with brave-tiger-42)
+
+4. Continue your own work. MCP notifications arrive as tasks complete.
+
+5. brave-tiger-42 completes → calm-falcon-17 auto-starts (dependencies satisfied)
+
+6. Review results:
+   - Read resource: task:///all
+   - tail -20 .super-agents/brave-tiger-42.output
+   - send_message({ task_id: "brave-tiger-42", message: "Add input validation" })
+```
 
 ## License
 

package/build/config/timeouts.d.ts

@@ -5,8 +5,4 @@ export declare const TASK_TIMEOUT_MIN_MS: number;
 export declare const TASK_TIMEOUT_MAX_MS: number;
 export declare const TASK_TIMEOUT_DEFAULT_MS: number;
 export declare const TASK_STALL_WARN_MS: number;
-export declare const COPILOT_SWITCH_COMMAND_TIMEOUT_MS: number;
-export declare const COPILOT_SWITCH_LOCK_STALE_MS: number;
-export declare const COPILOT_SWITCH_LOCK_TIMEOUT_MS: number;
-export declare const COPILOT_SWITCH_LOCK_POLL_MS: number;
 //# sourceMappingURL=timeouts.d.ts.map

package/build/config/timeouts.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,eAAO,MAAM,mBAAmB,QAA+C,CAAC;AAChF,eAAO,MAAM,mBAAmB,QAAmD,CAAC;AACpF,eAAO,MAAM,uBAAuB,QAA+C,CAAC;AACpF,eAAO,MAAM,kBAAkB,QAAmD,CAAC;AAGnF,eAAO,MAAM,iCAAiC,QAAuD,CAAC;AACtG,eAAO,MAAM,4BAA4B,QAA0D,CAAC;AACpG,eAAO,MAAM,8BAA8B,QAA4D,CAAC;AACxG,eAAO,MAAM,2BAA2B,QAAqD,CAAC"}
+{"version":3,"file":"timeouts.d.ts","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAUH,eAAO,MAAM,mBAAmB,QAA+C,CAAC;AAChF,eAAO,MAAM,mBAAmB,QAAmD,CAAC;AACpF,eAAO,MAAM,uBAAuB,QAA+C,CAAC;AACpF,eAAO,MAAM,kBAAkB,QAAmD,CAAC"}

package/build/config/timeouts.js

@@ -13,9 +13,4 @@ export const TASK_TIMEOUT_MIN_MS = readIntEnv('MCP_TASK_TIMEOUT_MIN_MS', 1_000);
 export const TASK_TIMEOUT_MAX_MS = readIntEnv('MCP_TASK_TIMEOUT_MAX_MS', 3_600_000);
 export const TASK_TIMEOUT_DEFAULT_MS = readIntEnv('MCP_TASK_TIMEOUT_MS', 1_800_000);
 export const TASK_STALL_WARN_MS = readIntEnv('MCP_TASK_STALL_WARN_MS', 5 * 60_000);
-// Copilot switch timings
-export const COPILOT_SWITCH_COMMAND_TIMEOUT_MS = readIntEnv('MCP_COPILOT_SWITCH_TIMEOUT_MS', 120_000);
-export const COPILOT_SWITCH_LOCK_STALE_MS = readIntEnv('MCP_COPILOT_SWITCH_LOCK_STALE_MS', 150_000);
-export const COPILOT_SWITCH_LOCK_TIMEOUT_MS = readIntEnv('MCP_COPILOT_SWITCH_LOCK_TIMEOUT_MS', 150_000);
-export const COPILOT_SWITCH_LOCK_POLL_MS = readIntEnv('MCP_COPILOT_SWITCH_LOCK_POLL_MS', 500);
 //# sourceMappingURL=timeouts.js.map

package/build/config/timeouts.js.map

@@ -1 +1 @@
-{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC,wBAAwB,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC;AAEnF,yBAAyB;AACzB,MAAM,CAAC,MAAM,iCAAiC,GAAG,UAAU,CAAC,+BAA+B,EAAE,OAAO,CAAC,CAAC;AACtG,MAAM,CAAC,MAAM,4BAA4B,GAAG,UAAU,CAAC,kCAAkC,EAAE,OAAO,CAAC,CAAC;AACpG,MAAM,CAAC,MAAM,8BAA8B,GAAG,UAAU,CAAC,oCAAoC,EAAE,OAAO,CAAC,CAAC;AACxG,MAAM,CAAC,MAAM,2BAA2B,GAAG,UAAU,CAAC,iCAAiC,EAAE,GAAG,CAAC,CAAC"}
+{"version":3,"file":"timeouts.js","sourceRoot":"","sources":["../../src/config/timeouts.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,SAAS,UAAU,CAAC,IAAY,EAAE,QAAgB;IAChD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC9B,IAAI,CAAC,GAAG;QAAE,OAAO,QAAQ,CAAC;IAC1B,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC;IAC1B,OAAO,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;AAC5E,CAAC;AAED,gCAAgC;AAChC,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,KAAK,CAAC,CAAC;AAChF,MAAM,CAAC,MAAM,mBAAmB,GAAG,UAAU,CAAC,yBAAyB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,uBAAuB,GAAG,UAAU,CAAC,qBAAqB,EAAE,SAAS,CAAC,CAAC;AACpF,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC,wBAAwB,EAAE,CAAC,GAAG,MAAM,CAAC,CAAC"}