gsd-unsupervised 1.0.0

package/README.md

@@ -0,0 +1,263 @@
+### gsd-unsupervised
+
+Autonomous orchestrator that drives Cursor's headless agent through the full [GSD (Get Shit Done)](https://github.com/get-shit-done) lifecycle. It reads goals from a queue, invokes `cursor-agent` with GSD commands, monitors progress via `.planning/STATE.md`, and advances phases automatically. Built for reliable, hands-off goal-to-completion automation on a single machine.
+
+## Features
+
+- **Goal queue** — Define work in `goals.md`; the daemon processes pending goals sequentially or in parallel.
+- **GSD lifecycle** — Runs `/gsd/new-project` → `/gsd/create-roadmap` → `/gsd/plan-phase` → `/gsd/execute-plan` in the correct order.
+- **Cursor agent integration** — Spawns `cursor-agent` headlessly, streams commands, and handles process lifecycle (timeouts, tree-kill on shutdown).
+- **State monitoring** — Watches `.planning/STATE.md` for phase/plan progress and emits events (phase_advanced, plan_advanced, phase_completed, goal_completed).
+- **Crash detection & recovery** — Session log at project root, resume from exact phase/plan on next run, heartbeat for liveness.
+- **Resource governor** — CPU + memory headroom checks before each agent call so the daemon backs off instead of thrashing your box.
+- **Local status dashboard** — Optional HTTP server (`--status-server <port>`) serving an HTML dashboard and `/api/status` JSON. Use `--ngrok` to have the daemon run `ngrok http <port>` so the dashboard is reachable via a public URL while the process runs.
+- **Optional SMS (Twilio)** — Notifications for goal complete, goal failed, and daemon paused; requires `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_FROM`, `TWILIO_TO`. If unset, the daemon runs without SMS.
+
+## Prerequisites
+
+- **Node.js** ≥ 18
+- **Cursor** with GSD rules installed (e.g. in `.cursor/rules/`)
+- **cursor-agent** CLI (path configurable; default `agent`)
+- **CURSOR_API_KEY** — Required for live runs. Get from Cursor Dashboard → Cloud Agents → User API Keys. Not required for `--dry-run`.
+
+### WSL Support & Paths
+
+This project is WSL-aware and includes helpers for path resolution when running under WSL2:
+
+- **WSL detection** lives in `src/config/wsl.ts`, which can answer whether the current process is running under WSL and convert `/mnt/<drive>/...` paths to Windows-style `X:\...` paths.
+- **Centralized path resolution** is provided by `src/config/paths.ts`:
+  - `getCursorBinaryPath` chooses the effective Cursor agent binary path, preferring the `GSD_CURSOR_BIN` environment variable, then `cursorAgentPath` from config, and finally falling back to `cursor-agent`. On WSL it can map `/mnt/*` paths to Windows-style paths when needed.
+  - `getClipExePath` resolves a Windows `clip.exe` location when running under WSL (defaulting to `C:\Windows\System32\clip.exe`), or returns `null` when clipboard integration is unavailable.
+  - `getWorkspaceDisplayPath` exposes both the WSL path and, when possible, a corresponding Windows path for the workspace root.
+- **WSL bootstrap** in `src/bootstrap/wsl-bootstrap.ts` wires these helpers together and is invoked from the CLI startup so the daemon has a single place to understand the current environment.
+
+When `clip.exe` cannot be resolved (for example, on non-WSL Linux), clipboard integration should be treated as optional by higher-level tooling: consumers should check for `null` and simply skip clipboard-related features instead of failing daemon startup.
+
+## Install
+
+From npm (recommended):
+
+```bash
+npm install -g gsd-unsupervised
+# or
+npx gsd-unsupervised init
+```
+
+From source:
+
+```bash
+git clone <repo-url>
+cd gsd-unsupervised
+npm install
+npm run build
+```
+
+### WSL Bootstrap (one command)
+
+On WSL2, from the project root:
+
+```bash
+bash setup.sh              # Detect WSL2, sync GSD rules from Windows .cursor into repo
+bash setup.sh --dry-run     # Show what would be done (no changes)
+bash setup.sh --validate    # Bootstrap + validation checks + orchestrator smoke test
+```
+
+**Prerequisites:** WSL2, Cursor installed on Windows with GSD rules in `.cursor/rules`, and (for `--validate`) Node.js ≥18 and npm. A successful run creates or updates `.cursor/rules` in the repo and (with `--validate`) runs the test suite. Re-runs are idempotent.
+
+## Usage
+
+### Two modes
+
+- **SELF** — Daemon improves this repo (`gsd-unsupervised`). Workspace and goals live here; state in `.gsd/state.json`.
+- **PROJECT** — Daemon works on another repo. You run `npx gsd-unsupervised init` in that repo; state and goals live under that repo’s `.gsd/`.
+
+### First-time setup (any repo)
+
+```bash
+npx gsd-unsupervised init
+```
+
+Prompts: project name, repo path, first goal, Twilio SMS (y/n), public dashboard via ngrok (y/n). Writes `.gsd/state.json`, goals, and optional `.env`. Then start with `./run`.
+
+### Recommended (dashboard + public URL)
+
+From the project root you can use the **`run`** script (reads `.gsd/state.json`, loads `.env`, starts daemon + optional ngrok + tmux):
+
+```bash
+./run
+```
+
+If there is no `.gsd/state.json`, run `npx gsd-unsupervised init` first.
+
+Or run the daemon explicitly with the status server and ngrok:
+
+```bash
+export CURSOR_API_KEY=your_key_here
+./bin/gsd-unsupervised --goals goals.md --status-server 4173 --ngrok --verbose
+```
+
+Extra args are passed through (e.g. `./run --parallel`).
+
+- **Status server** on port `4173`: open `http://localhost:4173` for the HTML dashboard.
+- **ngrok** runs `ngrok http 4173` for the same process; the public URL appears in the terminal. When the daemon exits, ngrok is stopped.
+
+Requires [ngrok](https://ngrok.com/) on your PATH and an ngrok authtoken (e.g. `ngrok config add-authtoken <token>`). Set `CURSOR_API_KEY` in your environment or in a `.env` file.
+
+### Other ways to run
+
+```bash
+# Preview the goal queue (no API key needed)
+./bin/gsd-unsupervised --dry-run --goals goals.md
+
+# Run without dashboard
+./bin/gsd-unsupervised --goals goals.md --verbose
+
+# Dashboard only (no ngrok, localhost only)
+./bin/gsd-unsupervised --goals goals.md --status-server 4173 --verbose
+```
+
+### CLI options
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `--goals <path>` | `./goals.md` | Path to the goals queue file |
+| `--config <path>` | `./.autopilot/config.json` | Config file (optional) |
+| `--parallel` | `false` | Enable parallel project execution |
+| `--max-concurrent <n>` | `3` | Max concurrent goals when `--parallel` |
+| `--verbose` | `false` | Debug logging and pretty output |
+| `--dry-run` | `false` | Parse goals and show plan only; no agent calls |
+| `--agent <name>` | `cursor` | Agent type: `cursor`, `claude-code`, `gemini-cli`, `codex`. Invalid names fail fast. |
+| `--agent-path <path>` | `agent` | Path to cursor-agent binary |
+| `--agent-timeout <ms>` | `600000` | Agent invocation timeout (ms) |
+| `--status-server <port>` | — | Enable local HTTP status server: GET / = dashboard HTML, GET /status or /api/status = JSON |
+| `--ngrok` | `false` | Start `ngrok http <port>` when status server is enabled; tunnel and process share the same lifecycle |
+
+### Agent selection (`--agent`)
+
+The `--agent` flag selects which AI coding agent the orchestrator invokes. Supported values: `cursor` (default), `claude-code`, `gemini-cli`, `codex`. Invalid names fail fast at startup and do not start the daemon. Omitting the flag or using `--agent=cursor` yields identical behavior to the original Cursor-only implementation (backward compatible). Non-Cursor agents are currently stub placeholders (TODO).
+
+### Goals file (`goals.md`)
+
+Use sections **Pending**, **In Progress**, and **Done**. List goals as markdown checkboxes under the right section. The orchestrator processes items in **Pending** and moves them to **In Progress** / **Done** as it runs.
+
+Example:
+
+```markdown
+## Pending
+- [ ] Your next goal
+
+## In Progress
+<!-- moved here while running -->
+
+## Done
+<!-- completed goals -->
+```
+
+All roadmap phases (1–7) are implemented: Foundation, Lifecycle, Agent Integration, State Monitoring, Crash Detection & Recovery, Status Server, WSL Bootstrap. Use `goals.md` for new work items.
+
+## Configuration
+
+Config can come from a JSON file (`--config`) and is overridden by CLI options. All fields are optional.
+
+| Field | Default | Description |
+|-------|---------|-------------|
+| `goalsPath` | `"./goals.md"` | Goals file path |
+| `parallel` | `false` | Parallel mode |
+| `maxConcurrent` | `3` | Max concurrent goals (1–10) |
+| `verbose` | `false` | Verbose logging |
+| `logLevel` | `"info"` | `debug` \| `info` \| `warn` \| `error` |
+| `workspaceRoot` | `process.cwd()` | Project root (for `.planning/`, etc.) |
+| `agent` | `"cursor"` | Agent type: `cursor`, `claude-code`, `gemini-cli`, `codex` |
+| `cursorAgentPath` | `"cursor-agent"` | cursor-agent binary path |
+| `agentTimeoutMs` | `600000` | Agent timeout (≥ 10000) |
+| `sessionLogPath` | `"./session-log.jsonl"` | Session log file |
+| `stateWatchDebounceMs` | `500` | STATE.md watcher debounce (≥ 100) |
+| `requireCleanGitBeforePlan` | `true` | Refuse execute-plan when git working tree is dirty |
+| `autoCheckpoint` | `false` | When true and tree dirty, create a checkpoint commit before plan |
+| `statusServerPort` | — | When set, start local HTTP status server on this port (dashboard + /api/status) |
+| `ngrok` | `false` | When true and status server is enabled, run `ngrok http <port>` for the process lifetime |
+
+Example `.autopilot/config.json`:
+
+```json
+{
+  "goalsPath": "./goals.md",
+  "verbose": true,
+  "stateWatchDebounceMs": 500
+}
+```
+
+## Project structure
+
+```
+├── bin/gsd-unsupervised     # CLI entry (Node)
+├── src/
+│   ├── cli.ts            # Commander setup, dry-run, daemon entry
+│   ├── config.ts         # Zod config schema and loader
+│   ├── daemon.ts         # Goal loop, StateWatcher per goal
+│   ├── orchestrator.ts   # GSD state machine, agent invoker, reportProgress
+│   ├── lifecycle.ts     # Goal phases and command sequence
+│   ├── goals.ts         # goals.md parser
+│   ├── roadmap-parser.ts # ROADMAP.md / phase / plan discovery
+│   ├── state-parser.ts   # STATE.md "Current Position" parser
+│   ├── state-watcher.ts  # Chokidar watcher, progress events
+│   ├── cursor-agent.ts   # cursor-agent invoker, API key validation
+│   ├── logger.ts        # Pino logger init
+│   └── ...
+├── .planning/            # GSD project state (STATE.md, ROADMAP.md, phases/)
+├── goals.md              # Goal queue
+└── package.json
+```
+
+See `docs/ARCHITECTURE.md` for module roles and data flow.
+
+## Crash detection and recovery
+
+The daemon appends one JSON line per agent run to **session-log.jsonl** at the project root (config `sessionLogPath`, default `./session-log.jsonl`). Each entry includes `goalTitle`, `phaseNumber`, `planNumber`, and `status` (`running` | `done` | `crashed` | `timeout`). On startup, if the last entry is `running` or `crashed` and the first pending goal matches, the daemon computes a resume point from STATE.md (or the log) and passes it to the orchestrator, which re-runs only that plan then continues.
+
+**Example session-log.jsonl (2 lines):**
+
+```jsonl
+{"timestamp":"2026-03-17T12:00:00.000Z","goalTitle":"Complete Phase 5","phase":"/gsd/execute-plan","phaseNumber":2,"planNumber":1,"sessionId":null,"command":"/gsd/execute-plan .planning/phases/02-x/02-01-PLAN.md","status":"running"}
+{"timestamp":"2026-03-17T12:05:00.000Z","goalTitle":"Complete Phase 5","phase":"/gsd/execute-plan","phaseNumber":2,"planNumber":1,"sessionId":"abc","command":"/gsd/execute-plan .planning/phases/02-x/02-01-PLAN.md","status":"crashed","durationMs":300000,"error":"Agent exited with code 1"}
+```
+
+**Corresponding STATE.md Current Position (when crash occurred):**
+
+```markdown
+## Current Position
+Phase: 2 of 7 (Core Orchestration Loop)
+Plan: 1 of 3 in current phase
+Status: Executing plan
+Last activity: 2026-03-17 — Running 02-01-PLAN.md
+Progress: ██░░░░░░░░ 14%
+```
+
+Resume uses this to re-run `execute-plan` for phase 2 plan 1 only, then continue.
+
+- **requireCleanGitBeforePlan** (default `true`): the orchestrator refuses to run `execute-plan` when the git working tree has uncommitted changes, unless **autoCheckpoint** is `true`, in which case it creates a checkpoint commit first.
+- **How to recover manually:** (1) Inspect `session-log.jsonl` (last line = last run; `status` `crashed` or `running`). (2) Read `.planning/STATE.md` for "Current Position" (phase/plan). (3) Either run the daemon again with the same goal so it resumes automatically, or run `/gsd/execute-plan .planning/phases/<phase-dir>/<phase>-<plan>-PLAN.md` for the failed plan.
+
+**Status server and dashboard:** Use `--status-server <port>` to enable the local HTTP status server (e.g. `./bin/gsd-unsupervised --goals goals.md --status-server 4173`). Add `--ngrok` to have the daemon run `ngrok http <port>` for the same lifecycle: the public URL appears in ngrok’s output and the tunnel is closed when the daemon exits. `GET /` serves the HTML dashboard; `GET /status` returns legacy JSON; `GET /api/status` returns rich JSON including `stateSnapshot`, session log window, git feed, and `systemLoad`. `GET /api/config` and `POST /api/config` expose and update `.planning/config.json` (used for the sequential/parallel toggle).
+
+**Hot-reload and webhook:** The daemon watches `goals.md` and merges new pending goals into the queue when the file changes. With the status server running: **POST /api/goals** (JSON `{ "title": "...", "priority": 1 }`) appends to goals and enqueues; **POST /api/todos** (JSON `{ "title": "...", "area": "api" }`) creates `.planning/todos/pending/`; **POST /webhook/twilio** accepts inbound SMS (e.g. `add <goal>` or `todo <task>`) and replies with TwiML. Point your Twilio number webhook at `<ngrok-url>/webhook/twilio`.
+
+**Parallel goal pool:** With `--parallel`, a worker pool of size `--max-concurrent` is used; a per-workspace mutex keeps one goal running at a time for a single workspace (phase-level parallel inside execute-phase still applies).
+
+**SMS (Twilio):** Optional. Set `TWILIO_ACCOUNT_SID`, `TWILIO_AUTH_TOKEN`, `TWILIO_FROM`, and `TWILIO_TO` to receive SMS on goal complete, goal failed, and daemon paused (after 3 retries). If any are unset, SMS is skipped and the daemon runs normally.
+
+**State and heartbeat:** When started via `./run` or `gsd-unsupervised run --state .gsd/state.json`, the daemon writes to `.gsd/state.json` (PID, current goal, progress, `lastHeartbeat`). You can use `lastHeartbeat` in an external cron or script to send a periodic "alive" SMS (e.g. every 30 min) or alert if the heartbeat is stale (e.g. >10 min).
+
+## Development
+
+```bash
+npm run build    # Compile TypeScript
+npm test         # Run tests (Vitest)
+npm run dev      # Watch build
+```
+
+Tests include state parser, stream events, lifecycle, session-log, roadmap-parser, status-server, and resume integration. Run with `npm test` or `npm test -- state-parser`. Integration tests (crash/resume): `npm run test:integration`.
+
+## License
+
+MIT

package/bin/gsd-unsupervised

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import '../dist/cli.js';
+

package/bin/start-daemon.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+cd "$ROOT"
+
+# Thin wrapper around the CLI entrypoint so the daemon can be started via:
+#   bin/start-daemon.sh --goals ./goals.md --config ./.autopilot/config.json
+#
+# All arguments are forwarded to the underlying CLI.
+node dist/cli.js "$@"
+

package/bin/unsupervised-gsd

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/cli.js';

package/dist/agent-runner.d.ts

@@ -0,0 +1,26 @@
+import { type ChildProcess } from 'node:child_process';
+import { type CursorStreamEvent, type ResultEvent } from './stream-events.js';
+/** Supported agent IDs for the pluggable invoker seam. */
+export type AgentId = 'cursor' | 'claude-code' | 'gemini-cli' | 'codex';
+export declare const SUPPORTED_AGENTS: readonly AgentId[];
+export declare function isSupportedAgent(id: string): id is AgentId;
+export interface RunAgentOptions {
+    agentPath: string;
+    workspace: string;
+    prompt: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    model?: string;
+    resumeId?: string;
+    onEvent?: (event: CursorStreamEvent) => void;
+}
+export interface RunAgentResult {
+    sessionId: string | null;
+    resultEvent: ResultEvent | null;
+    events: CursorStreamEvent[];
+    exitCode: number | null;
+    timedOut: boolean;
+    stderr: string;
+}
+export declare function runAgent(options: RunAgentOptions): Promise<RunAgentResult>;
+export declare function abortAgent(child: ChildProcess): Promise<void>;

package/dist/agent-runner.js

@@ -0,0 +1,111 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import treeKill from 'tree-kill';
+import { parseEvent, extractSessionId, extractResult, } from './stream-events.js';
+export const SUPPORTED_AGENTS = [
+    'cursor',
+    'claude-code',
+    'gemini-cli',
+    'codex',
+];
+export function isSupportedAgent(id) {
+    return SUPPORTED_AGENTS.includes(id);
+}
+export function runAgent(options) {
+    const { agentPath, workspace, prompt, env, timeoutMs, model, resumeId, onEvent } = options;
+    const args = [
+        '-p', '--force', '--trust', '--approve-mcps',
+        '--workspace', workspace,
+        '--output-format', 'stream-json',
+    ];
+    if (model) {
+        args.push('--model', model);
+    }
+    if (resumeId) {
+        args.push('--resume', resumeId);
+    }
+    args.push(prompt);
+    return new Promise((resolve, reject) => {
+        let child;
+        try {
+            child = spawn(agentPath, args, {
+                stdio: ['pipe', 'pipe', 'pipe'],
+                env: { ...process.env, ...env },
+            });
+        }
+        catch (err) {
+            reject(new Error(`Failed to spawn agent at "${agentPath}": ${err instanceof Error ? err.message : String(err)}`));
+            return;
+        }
+        const events = [];
+        const stderrChunks = [];
+        let timedOut = false;
+        let timer;
+        child.on('error', (err) => {
+            if (timer)
+                clearTimeout(timer);
+            reject(new Error(`Failed to spawn agent at "${agentPath}": ${err.message}`));
+        });
+        if (child.stderr) {
+            child.stderr.on('data', (chunk) => {
+                stderrChunks.push(chunk.toString());
+            });
+        }
+        if (child.stdout) {
+            const rl = createInterface({ input: child.stdout });
+            rl.on('line', (line) => {
+                const event = parseEvent(line);
+                if (event) {
+                    events.push(event);
+                    onEvent?.(event);
+                }
+            });
+        }
+        if (timeoutMs != null && timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                abortAgent(child).catch(() => { });
+            }, timeoutMs);
+        }
+        child.on('close', (code) => {
+            if (timer)
+                clearTimeout(timer);
+            const resultEvent = extractResult(events);
+            const parts = stderrChunks.slice();
+            if (timedOut) {
+                parts.push(`Agent timed out after ${timeoutMs}ms`);
+            }
+            if (code === 0 && !resultEvent) {
+                parts.push('Agent exited cleanly but produced no result event');
+            }
+            resolve({
+                sessionId: extractSessionId(events),
+                resultEvent,
+                events,
+                exitCode: code,
+                timedOut,
+                stderr: parts.join(''),
+            });
+        });
+    });
+}
+export async function abortAgent(child) {
+    if (child.pid == null)
+        return;
+    return new Promise((resolve) => {
+        const killTimer = setTimeout(() => {
+            treeKill(child.pid, 'SIGKILL', () => resolve());
+        }, 5000);
+        treeKill(child.pid, 'SIGTERM', (err) => {
+            if (err) {
+                clearTimeout(killTimer);
+                treeKill(child.pid, 'SIGKILL', () => resolve());
+                return;
+            }
+            child.on('exit', () => {
+                clearTimeout(killTimer);
+                resolve();
+            });
+        });
+    });
+}

package/dist/agent-runner.spawn.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent-runner.spawn.test.js

@@ -0,0 +1,128 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { runAgent } from './agent-runner.js';
+function createMockChildProcess() {
+    const child = new EventEmitter();
+    child.pid = 12345;
+    child.stdout = new PassThrough();
+    child.stderr = new PassThrough();
+    return child;
+}
+const spawnMock = vi.fn();
+const treeKillMock = vi.fn();
+vi.mock('node:child_process', async () => {
+    const actual = await vi.importActual('node:child_process');
+    return {
+        ...actual,
+        spawn: ((...args) => spawnMock(...args)),
+    };
+});
+vi.mock('tree-kill', () => {
+    return {
+        default: ((...args) => treeKillMock(...args)),
+    };
+});
+describe('agent-runner spawn contract', () => {
+    beforeEach(() => {
+        spawnMock.mockReset();
+        treeKillMock.mockReset();
+        vi.useRealTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('spawns cursor-agent with stable args and prompt', async () => {
+        const child = createMockChildProcess();
+        spawnMock.mockReturnValue(child);
+        const p = runAgent({
+            agentPath: '/usr/bin/cursor-agent',
+            workspace: '/tmp/workspace',
+            prompt: '/gsd/execute-plan foo',
+            timeoutMs: 0,
+        });
+        child.emit('close', 0);
+        const result = await p;
+        expect(result.exitCode).toBe(0);
+        expect(result.timedOut).toBe(false);
+        expect(spawnMock).toHaveBeenCalledTimes(1);
+        const [agentPath, args, opts] = spawnMock.mock.calls[0];
+        expect(agentPath).toBe('/usr/bin/cursor-agent');
+        expect(args).toEqual([
+            '-p',
+            '--force',
+            '--trust',
+            '--approve-mcps',
+            '--workspace',
+            '/tmp/workspace',
+            '--output-format',
+            'stream-json',
+            '/gsd/execute-plan foo',
+        ]);
+        expect(opts.stdio).toEqual(['pipe', 'pipe', 'pipe']);
+    });
+    it('appends --model and --resume flags when provided', async () => {
+        const child = createMockChildProcess();
+        spawnMock.mockReturnValue(child);
+        const p = runAgent({
+            agentPath: 'cursor-agent',
+            workspace: '/w',
+            prompt: 'hello',
+            model: 'gpt-5',
+            resumeId: 'resume-123',
+            timeoutMs: 0,
+        });
+        child.emit('close', 0);
+        await p;
+        const [, args] = spawnMock.mock.calls[0];
+        expect(args).toEqual([
+            '-p',
+            '--force',
+            '--trust',
+            '--approve-mcps',
+            '--workspace',
+            '/w',
+            '--output-format',
+            'stream-json',
+            '--model',
+            'gpt-5',
+            '--resume',
+            'resume-123',
+            'hello',
+        ]);
+    });
+    it('merges env passthrough with provided env', async () => {
+        const child = createMockChildProcess();
+        spawnMock.mockReturnValue(child);
+        const p = runAgent({
+            agentPath: 'cursor-agent',
+            workspace: '/w',
+            prompt: 'hello',
+            env: { FOO: 'bar' },
+            timeoutMs: 0,
+        });
+        child.emit('close', 0);
+        await p;
+        const [, , opts] = spawnMock.mock.calls[0];
+        expect(opts.env).toMatchObject({ FOO: 'bar' });
+    });
+    it('aborts on timeout and resolves with timedOut: true', async () => {
+        vi.useFakeTimers();
+        const child = createMockChildProcess();
+        spawnMock.mockReturnValue(child);
+        // Simulate tree-kill completing immediately.
+        treeKillMock.mockImplementation(((_pid, _signal, cb) => cb?.(null)));
+        const promise = runAgent({
+            agentPath: 'cursor-agent',
+            workspace: '/w',
+            prompt: 'hello',
+            timeoutMs: 10,
+        });
+        await vi.advanceTimersByTimeAsync(10);
+        // runAgent only resolves after close; emit it after timeout fires.
+        child.emit('close', 0);
+        const result = await promise;
+        expect(result.timedOut).toBe(true);
+        expect(treeKillMock).toHaveBeenCalled();
+    });
+});

package/dist/agent-runner.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agent-runner.test.js

@@ -0,0 +1,26 @@
+import { describe, it, expect } from 'vitest';
+import { SUPPORTED_AGENTS, isSupportedAgent } from './agent-runner.js';
+describe('agent-runner', () => {
+    describe('SUPPORTED_AGENTS', () => {
+        it('includes cursor, claude-code, gemini-cli, codex', () => {
+            expect(SUPPORTED_AGENTS).toContain('cursor');
+            expect(SUPPORTED_AGENTS).toContain('claude-code');
+            expect(SUPPORTED_AGENTS).toContain('gemini-cli');
+            expect(SUPPORTED_AGENTS).toContain('codex');
+            expect(SUPPORTED_AGENTS).toHaveLength(4);
+        });
+    });
+    describe('isSupportedAgent', () => {
+        it('returns true for supported agents', () => {
+            expect(isSupportedAgent('cursor')).toBe(true);
+            expect(isSupportedAgent('claude-code')).toBe(true);
+            expect(isSupportedAgent('gemini-cli')).toBe(true);
+            expect(isSupportedAgent('codex')).toBe(true);
+        });
+        it('returns false for invalid agents', () => {
+            expect(isSupportedAgent('bogus-agent')).toBe(false);
+            expect(isSupportedAgent('')).toBe(false);
+            expect(isSupportedAgent('Cursor')).toBe(false);
+        });
+    });
+});

package/dist/bootstrap/wsl-bootstrap.d.ts

@@ -0,0 +1,11 @@
+import type { AutopilotConfig } from '../config.js';
+export interface ResolvedEnvironment {
+    isWsl: boolean;
+    cursorBinaryPath: string;
+    clipExePath: string | null;
+    workspace: {
+        wslPath: string;
+        windowsPath: string | null;
+    };
+}
+export declare function applyWslBootstrap(config: AutopilotConfig): ResolvedEnvironment;

package/dist/bootstrap/wsl-bootstrap.js

@@ -0,0 +1,14 @@
+import { isWsl } from '../config/wsl.js';
+import { getClipExePath, getCursorBinaryPath, getWorkspaceDisplayPath, } from '../config/paths.js';
+export function applyWslBootstrap(config) {
+    const isWslEnv = isWsl();
+    const cursorBinaryPath = getCursorBinaryPath(config);
+    const clipExePath = getClipExePath();
+    const workspace = getWorkspaceDisplayPath(config.workspaceRoot);
+    return {
+        isWsl: isWslEnv,
+        cursorBinaryPath,
+        clipExePath,
+        workspace,
+    };
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export declare function main(): void;