gsd-unsupervised 1.0.0

package/dist/cli.js

@@ -0,0 +1,172 @@
+import * as dotenv from 'dotenv';
+dotenv.config();
+import { Command } from 'commander';
+import { readFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import { initLogger, createChildLogger } from './logger.js';
+import { loadConfig } from './config.js';
+import { loadGoals, getPendingGoals } from './goals.js';
+import { runDaemon, registerShutdownHandlers } from './daemon.js';
+import { validateCursorApiKey } from './cursor-agent.js';
+import { applyWslBootstrap } from './bootstrap/wsl-bootstrap.js';
+import { readGsdStateFromPath } from './gsd-state.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+function getVersion() {
+    const pkgPath = resolve(__dirname, '..', 'package.json');
+    const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'));
+    return pkg.version;
+}
+const program = new Command();
+/** Default action: legacy direct daemon (goals, status-server, etc.). */
+program
+    .name('gsd-unsupervised')
+    .description('Autonomous orchestrator for Cursor agent + GSD framework')
+    .version(getVersion())
+    .option('--goals <path>', 'Path to goals.md file', './goals.md')
+    .option('--config <path>', 'Path to config JSON file', './.autopilot/config.json')
+    .option('--parallel', 'Enable parallel project execution', false)
+    .option('--max-concurrent <n>', 'Max concurrent projects when parallel', '3')
+    .option('--verbose', 'Enable verbose/debug logging', false)
+    .option('--dry-run', 'Parse goals and show plan without executing', false)
+    .option('--agent <name>', 'Agent type: cursor (default), claude-code, gemini-cli, codex', 'cursor')
+    .option('--agent-path <path>', 'Path to cursor-agent binary', 'agent')
+    .option('--agent-timeout <ms>', 'Agent invocation timeout in milliseconds', '600000')
+    .option('--status-server <port>', 'Enable HTTP status server on port (GET / or /status)', undefined)
+    .option('--ngrok', 'Start ngrok tunnel to status server port (use with --status-server)', false)
+    .action(async (opts) => {
+    const verbose = opts.verbose;
+    const logger = initLogger({
+        level: verbose ? 'debug' : 'info',
+        pretty: verbose,
+    });
+    const log = createChildLogger(logger, 'cli');
+    try {
+        const config = loadConfig({
+            configPath: opts.config,
+            cliOverrides: {
+                goalsPath: opts.goals,
+                parallel: opts.parallel,
+                maxConcurrent: parseInt(opts.maxConcurrent, 10),
+                verbose,
+                agent: opts.agent,
+                cursorAgentPath: opts.agentPath,
+                agentTimeoutMs: parseInt(opts.agentTimeout, 10),
+                statusServerPort: opts.statusServer ? parseInt(opts.statusServer, 10) : undefined,
+                ngrok: opts.ngrok,
+            },
+        });
+        log.debug({ config }, 'Configuration loaded');
+        const resolvedEnv = applyWslBootstrap(config);
+        log.debug({
+            isWsl: resolvedEnv.isWsl,
+            cursorBinaryPath: resolvedEnv.cursorBinaryPath,
+            clipExePath: resolvedEnv.clipExePath ?? undefined,
+            workspace: resolvedEnv.workspace,
+        }, 'Resolved environment for current platform');
+        if (!opts.dryRun && config.agent === 'cursor') {
+            try {
+                validateCursorApiKey();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Error: ${message}\n`);
+                process.exit(1);
+            }
+        }
+        if (opts.dryRun) {
+            const goals = await loadGoals(config.goalsPath);
+            const pending = getPendingGoals(goals);
+            console.log('\n  Goals Queue Summary');
+            console.log('  ' + '─'.repeat(60));
+            console.log('  ' +
+                'Title'.padEnd(50) +
+                'Status');
+            console.log('  ' + '─'.repeat(60));
+            for (const g of goals) {
+                console.log('  ' +
+                    g.title.slice(0, 49).padEnd(50) +
+                    g.status);
+            }
+            console.log('  ' + '─'.repeat(60));
+            console.log(`  Total: ${goals.length}  |  Pending: ${pending.length}\n`);
+            return;
+        }
+        registerShutdownHandlers(logger);
+        await runDaemon(config, logger);
+    }
+    catch (err) {
+        log.error({ err }, 'Fatal error');
+        process.exit(1);
+    }
+});
+/** Run daemon from .gsd/state.json (used by ./run script). */
+program
+    .command('run')
+    .description('Start daemon using .gsd/state.json (single source of truth)')
+    .option('--state <path>', 'Path to .gsd/state.json', undefined)
+    .option('--verbose', 'Verbose logging', false)
+    .action(async (opts) => {
+    const cwd = process.cwd();
+    const statePath = opts.state
+        ? resolve(cwd, opts.state)
+        : resolve(cwd, '.gsd', 'state.json');
+    if (!existsSync(statePath)) {
+        console.error('No state found. Run: npx gsd-unsupervised init');
+        process.exit(1);
+    }
+    const projectRoot = dirname(dirname(statePath));
+    const state = await readGsdStateFromPath(statePath, projectRoot);
+    if (!state) {
+        console.error('Invalid or empty state at', statePath);
+        process.exit(1);
+    }
+    const workspaceRoot = resolve(projectRoot, state.workspaceRoot);
+    const goalsPath = state.goalsPath.startsWith('/')
+        ? state.goalsPath
+        : resolve(workspaceRoot, state.goalsPath);
+    const verbose = opts.verbose;
+    const logger = initLogger({ level: verbose ? 'debug' : 'info', pretty: verbose });
+    const log = createChildLogger(logger, 'cli');
+    try {
+        const config = loadConfig({
+            cliOverrides: {
+                workspaceRoot,
+                goalsPath,
+                statusServerPort: state.statusServerPort,
+                statePath,
+                verbose,
+            },
+        });
+        log.info({ mode: state.mode, project: state.project, goalsPath: config.goalsPath }, 'Resuming from state');
+        if (config.agent === 'cursor') {
+            try {
+                validateCursorApiKey();
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                process.stderr.write(`Error: ${message}\n`);
+                process.exit(1);
+            }
+        }
+        registerShutdownHandlers(logger);
+        await runDaemon(config, logger);
+    }
+    catch (err) {
+        log.error({ err }, 'Fatal error');
+        process.exit(1);
+    }
+});
+/** Onboarding wizard: create .gsd/ and goals. */
+program
+    .command('init')
+    .description('Onboarding wizard: project name, repo path, first goal, Twilio/ngrok config')
+    .action(async () => {
+    const { runInit } = await import('./init-wizard.js');
+    await runInit();
+});
+export function main() {
+    program.parse();
+}
+main();

package/dist/config/paths.d.ts

@@ -0,0 +1,8 @@
+import type { AutopilotConfig } from '../config.js';
+export declare function getCursorBinaryPath(config: AutopilotConfig): string;
+export declare function getClipExePath(): string | null;
+export interface WorkspaceDisplayPath {
+    wslPath: string;
+    windowsPath: string | null;
+}
+export declare function getWorkspaceDisplayPath(workspaceRoot: string): WorkspaceDisplayPath;

package/dist/config/paths.js

@@ -0,0 +1,36 @@
+import { isWsl, toWindowsPath } from './wsl.js';
+export function getCursorBinaryPath(config) {
+    const override = process.env.GSD_CURSOR_BIN;
+    if (override && override.trim() !== '') {
+        return override.trim();
+    }
+    const configured = config.cursorAgentPath ?? 'cursor-agent';
+    if (isWsl()) {
+        const maybeWindows = toWindowsPath(configured);
+        if (maybeWindows) {
+            return maybeWindows;
+        }
+    }
+    return configured;
+}
+export function getClipExePath() {
+    if (!isWsl())
+        return null;
+    const fromEnv = process.env.GSD_CLIP_EXE;
+    if (fromEnv && fromEnv.trim() !== '') {
+        return fromEnv.trim();
+    }
+    const windowsRoot = toWindowsPath('/mnt/c');
+    if (!windowsRoot || !windowsRoot.startsWith('C:\\')) {
+        return null;
+    }
+    return 'C:\\Windows\\System32\\clip.exe';
+}
+export function getWorkspaceDisplayPath(workspaceRoot) {
+    const wslPath = workspaceRoot;
+    if (!isWsl()) {
+        return { wslPath, windowsPath: null };
+    }
+    const windowsPath = toWindowsPath(workspaceRoot) ?? null;
+    return { wslPath, windowsPath };
+}

package/dist/config/wsl.d.ts

@@ -0,0 +1,4 @@
+export declare function isWindows(): boolean;
+export declare function isWsl(): boolean;
+export declare function getWindowsRoot(): string | null;
+export declare function toWindowsPath(wslPath: string): string | null;

package/dist/config/wsl.js

@@ -0,0 +1,43 @@
+import { readFileSync } from 'node:fs';
+const WSL_ENV_VARS = ['WSL_DISTRO_NAME', 'WSL_INTEROP'];
+export function isWindows() {
+    return process.platform === 'win32';
+}
+export function isWsl() {
+    if (process.platform !== 'linux')
+        return false;
+    for (const key of WSL_ENV_VARS) {
+        if (process.env[key])
+            return true;
+    }
+    try {
+        const contents = readFileSync('/proc/version', 'utf-8').toLowerCase();
+        if (contents.includes('microsoft') || contents.includes('wsl')) {
+            return true;
+        }
+    }
+    catch {
+        // Ignore – conservative fallback is "not WSL".
+    }
+    return false;
+}
+export function getWindowsRoot() {
+    if (!isWsl())
+        return null;
+    // For now we assume the standard /mnt/c mount; callers can handle null.
+    return '/mnt/c';
+}
+export function toWindowsPath(wslPath) {
+    if (!wslPath.startsWith('/mnt/'))
+        return null;
+    const segments = wslPath.split('/');
+    // ['', 'mnt', '<drive>', ...]
+    if (segments.length < 4)
+        return null;
+    const driveLetter = segments[2];
+    if (!/^[a-zA-Z]$/.test(driveLetter))
+        return null;
+    const rest = segments.slice(3).join('\\');
+    const drive = driveLetter.toUpperCase();
+    return rest ? `${drive}:\\${rest}` : `${drive}:\\`;
+}

package/dist/config.d.ts

@@ -0,0 +1,79 @@
+import { z } from 'zod';
+export declare const AgentIdSchema: z.ZodEnum<[string, ...string[]]>;
+export declare const AutopilotConfigSchema: z.ZodObject<{
+    goalsPath: z.ZodDefault<z.ZodString>;
+    parallel: z.ZodDefault<z.ZodBoolean>;
+    maxConcurrent: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Upper bound on allowed CPU usage before new agent work waits.
+     * Expressed as a fraction of total CPU capacity (1.0 = 100% of all cores).
+     */
+    maxCpuFraction: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Upper bound on allowed memory usage before new agent work waits.
+     * Expressed as a fraction of total system memory (1.0 = 100% of RAM).
+     */
+    maxMemoryFraction: z.ZodDefault<z.ZodNumber>;
+    verbose: z.ZodDefault<z.ZodBoolean>;
+    logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error"]>>;
+    workspaceRoot: z.ZodDefault<z.ZodString>;
+    /** Agent type: cursor (default), claude-code, gemini-cli, codex. Invalid values fail validation. */
+    agent: z.ZodDefault<z.ZodEnum<[string, ...string[]]>>;
+    cursorAgentPath: z.ZodDefault<z.ZodString>;
+    agentTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    sessionLogPath: z.ZodDefault<z.ZodString>;
+    stateWatchDebounceMs: z.ZodDefault<z.ZodNumber>;
+    /** When true, refuse execute-plan when git working tree is dirty (default true). */
+    requireCleanGitBeforePlan: z.ZodDefault<z.ZodBoolean>;
+    /** When true and tree is dirty, create a checkpoint commit before execute-plan (default false). */
+    autoCheckpoint: z.ZodDefault<z.ZodBoolean>;
+    /** When set, start HTTP status server on this port (GET / or /status returns JSON). */
+    statusServerPort: z.ZodOptional<z.ZodNumber>;
+    /** When true and statusServerPort is set, spawn `ngrok http <port>` for the duration of the daemon. */
+    ngrok: z.ZodDefault<z.ZodBoolean>;
+    /** When set, daemon writes PID, progress, lastHeartbeat to this state file (.gsd/state.json). */
+    statePath: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    goalsPath: string;
+    parallel: boolean;
+    maxConcurrent: number;
+    maxCpuFraction: number;
+    maxMemoryFraction: number;
+    verbose: boolean;
+    logLevel: "error" | "warn" | "info" | "debug";
+    workspaceRoot: string;
+    agent: string;
+    cursorAgentPath: string;
+    agentTimeoutMs: number;
+    sessionLogPath: string;
+    stateWatchDebounceMs: number;
+    requireCleanGitBeforePlan: boolean;
+    autoCheckpoint: boolean;
+    ngrok: boolean;
+    statusServerPort?: number | undefined;
+    statePath?: string | undefined;
+}, {
+    goalsPath?: string | undefined;
+    parallel?: boolean | undefined;
+    maxConcurrent?: number | undefined;
+    maxCpuFraction?: number | undefined;
+    maxMemoryFraction?: number | undefined;
+    verbose?: boolean | undefined;
+    logLevel?: "error" | "warn" | "info" | "debug" | undefined;
+    workspaceRoot?: string | undefined;
+    agent?: string | undefined;
+    cursorAgentPath?: string | undefined;
+    agentTimeoutMs?: number | undefined;
+    sessionLogPath?: string | undefined;
+    stateWatchDebounceMs?: number | undefined;
+    requireCleanGitBeforePlan?: boolean | undefined;
+    autoCheckpoint?: boolean | undefined;
+    statusServerPort?: number | undefined;
+    ngrok?: boolean | undefined;
+    statePath?: string | undefined;
+}>;
+export type AutopilotConfig = z.infer<typeof AutopilotConfigSchema>;
+export declare function loadConfig(options: {
+    configPath?: string;
+    cliOverrides?: Partial<AutopilotConfig>;
+}): AutopilotConfig;

package/dist/config.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { SUPPORTED_AGENTS } from './agent-runner.js';
+export const AgentIdSchema = z.enum(SUPPORTED_AGENTS);
+export const AutopilotConfigSchema = z.object({
+    goalsPath: z.string().default('./goals.md'),
+    parallel: z.boolean().default(false),
+    maxConcurrent: z.number().int().min(1).max(10).default(3),
+    /**
+     * Upper bound on allowed CPU usage before new agent work waits.
+     * Expressed as a fraction of total CPU capacity (1.0 = 100% of all cores).
+     */
+    maxCpuFraction: z.number().min(0.1).max(1).default(0.75),
+    /**
+     * Upper bound on allowed memory usage before new agent work waits.
+     * Expressed as a fraction of total system memory (1.0 = 100% of RAM).
+     */
+    maxMemoryFraction: z.number().min(0.5).max(1).default(0.9),
+    verbose: z.boolean().default(false),
+    logLevel: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+    workspaceRoot: z.string().default(process.cwd()),
+    /** Agent type: cursor (default), claude-code, gemini-cli, codex. Invalid values fail validation. */
+    agent: AgentIdSchema.default('cursor'),
+    cursorAgentPath: z.string().default('cursor-agent'),
+    agentTimeoutMs: z.number().int().min(10000).default(600000),
+    sessionLogPath: z.string().default('./session-log.jsonl'),
+    stateWatchDebounceMs: z.number().int().min(100).default(500),
+    /** When true, refuse execute-plan when git working tree is dirty (default true). */
+    requireCleanGitBeforePlan: z.boolean().default(true),
+    /** When true and tree is dirty, create a checkpoint commit before execute-plan (default false). */
+    autoCheckpoint: z.boolean().default(false),
+    /** When set, start HTTP status server on this port (GET / or /status returns JSON). */
+    statusServerPort: z.number().int().min(1).max(65535).optional(),
+    /** When true and statusServerPort is set, spawn `ngrok http <port>` for the duration of the daemon. */
+    ngrok: z.boolean().default(false),
+    /** When set, daemon writes PID, progress, lastHeartbeat to this state file (.gsd/state.json). */
+    statePath: z.string().optional(),
+});
+export function loadConfig(options) {
+    const { configPath, cliOverrides } = options;
+    let fileValues = {};
+    if (configPath && existsSync(configPath)) {
+        const raw = readFileSync(configPath, 'utf-8');
+        fileValues = JSON.parse(raw);
+    }
+    const workspaceRoot = cliOverrides?.workspaceRoot ??
+        fileValues.workspaceRoot ??
+        process.cwd();
+    // `.planning/config.json` is primarily for GSD framework behavior, but we also
+    // allow it to override a small set of daemon runtime flags (e.g. autoCheckpoint).
+    const planningOverrides = readPlanningOverrides(workspaceRoot);
+    const merged = {
+        ...fileValues,
+        ...planningOverrides,
+        ...stripUndefined(cliOverrides ?? {}),
+    };
+    const result = AutopilotConfigSchema.safeParse(merged);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  ${i.path.join('.')}: ${i.message}`)
+            .join('\n');
+        throw new Error(`Config validation failed:\n${issues}`);
+    }
+    return result.data;
+}
+function stripUndefined(obj) {
+    return Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+}
+function readPlanningOverrides(workspaceRoot) {
+    try {
+        const planningPath = path.join(workspaceRoot, '.planning', 'config.json');
+        if (!existsSync(planningPath))
+            return {};
+        const raw = readFileSync(planningPath, 'utf-8');
+        const parsed = JSON.parse(raw);
+        const overrides = {};
+        if (typeof parsed.autoCheckpoint === 'boolean') {
+            overrides.autoCheckpoint = parsed.autoCheckpoint;
+        }
+        if (typeof parsed.maxConcurrent === 'number') {
+            overrides.maxConcurrent = parsed.maxConcurrent;
+        }
+        if (typeof parsed.maxCpuFraction === 'number') {
+            overrides.maxCpuFraction = parsed.maxCpuFraction;
+        }
+        if (typeof parsed.maxMemoryFraction === 'number') {
+            overrides.maxMemoryFraction = parsed.maxMemoryFraction;
+        }
+        return overrides;
+    }
+    catch {
+        return {};
+    }
+}

package/dist/config.test.d.ts

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

package/dist/config.test.js

@@ -0,0 +1,27 @@
+import { describe, it, expect } from 'vitest';
+import { loadConfig } from './config.js';
+describe('config agent', () => {
+    it('defaults agent to cursor when not specified', () => {
+        const config = loadConfig({ cliOverrides: {} });
+        expect(config.agent).toBe('cursor');
+    });
+    it('accepts agent cursor when explicitly set', () => {
+        const config = loadConfig({ cliOverrides: { agent: 'cursor' } });
+        expect(config.agent).toBe('cursor');
+    });
+    it('accepts agent claude-code', () => {
+        const config = loadConfig({ cliOverrides: { agent: 'claude-code' } });
+        expect(config.agent).toBe('claude-code');
+    });
+    it('accepts agent gemini-cli', () => {
+        const config = loadConfig({ cliOverrides: { agent: 'gemini-cli' } });
+        expect(config.agent).toBe('gemini-cli');
+    });
+    it('accepts agent codex', () => {
+        const config = loadConfig({ cliOverrides: { agent: 'codex' } });
+        expect(config.agent).toBe('codex');
+    });
+    it('rejects invalid agent with clear error', () => {
+        expect(() => loadConfig({ cliOverrides: { agent: 'bogus-agent' } })).toThrow(/Invalid enum value.*Expected 'cursor' \| 'claude-code' \| 'gemini-cli' \| 'codex'.*received 'bogus-agent'/);
+    });
+});

package/dist/cursor-agent.d.ts

@@ -0,0 +1,17 @@
+import type { AgentInvoker } from './orchestrator.js';
+import type { AgentId } from './agent-runner.js';
+import { type SessionLogContext } from './session-log.js';
+import type { AutopilotConfig } from './config.js';
+export type { SessionLogContext };
+export interface CursorAgentConfig {
+    agentPath: string;
+    defaultTimeoutMs: number;
+    sessionLogPath: string;
+    /** If set, write heartbeat timestamp here while agent runs (for crash detection). */
+    heartbeatPath?: string;
+    heartbeatIntervalMs?: number;
+}
+export declare function createCursorAgentInvoker(agentConfig: CursorAgentConfig): AgentInvoker;
+export declare function validateCursorApiKey(): void;
+/** Agent-agnostic factory: returns the appropriate invoker for the given agent ID. */
+export declare function createAgentInvoker(agentId: AgentId, config: AutopilotConfig): AgentInvoker;

package/dist/cursor-agent.invoker.test.d.ts

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

package/dist/cursor-agent.invoker.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { createCursorAgentInvoker } from './cursor-agent.js';
+import { initLogger } from './logger.js';
+const appendSessionLogMock = vi.fn();
+const runAgentMock = vi.fn();
+vi.mock('./session-log.js', async () => {
+    const actual = await vi.importActual('./session-log.js');
+    return {
+        ...actual,
+        appendSessionLog: (...args) => appendSessionLogMock(...args),
+    };
+});
+vi.mock('./agent-runner.js', async () => {
+    const actual = await vi.importActual('./agent-runner.js');
+    return {
+        ...actual,
+        runAgent: (...args) => runAgentMock(...args),
+    };
+});
+const writeFileMock = vi.fn();
+const unlinkMock = vi.fn();
+vi.mock('node:fs/promises', async () => {
+    const actual = await vi.importActual('node:fs/promises');
+    return {
+        ...actual,
+        writeFile: (...args) => writeFileMock(...args),
+        unlink: (...args) => unlinkMock(...args),
+    };
+});
+function baseInvokerConfig(overrides) {
+    return {
+        agentPath: '/usr/bin/cursor-agent',
+        defaultTimeoutMs: 10_000,
+        sessionLogPath: '/tmp/session-log.jsonl',
+        heartbeatPath: '/tmp/heartbeat.txt',
+        heartbeatIntervalMs: 50,
+        ...overrides,
+    };
+}
+function resultEventSuccess() {
+    return {
+        type: 'result',
+        is_error: false,
+        duration_ms: 1,
+        result: 'ok',
+    };
+}
+function systemInit(sessionId = 'sess-1') {
+    return {
+        type: 'system',
+        subtype: 'init',
+        session_id: sessionId,
+    };
+}
+describe('cursor-agent invoker', () => {
+    const logger = initLogger({ level: 'silent', pretty: false });
+    beforeEach(() => {
+        appendSessionLogMock.mockReset();
+        runAgentMock.mockReset();
+        writeFileMock.mockReset();
+        unlinkMock.mockReset();
+        writeFileMock.mockResolvedValue(undefined);
+        unlinkMock.mockResolvedValue(undefined);
+        vi.useRealTimers();
+    });
+    afterEach(() => {
+        vi.useRealTimers();
+    });
+    it('writes running then done session-log entries on success', async () => {
+        runAgentMock.mockResolvedValue({
+            sessionId: 'sess-1',
+            resultEvent: resultEventSuccess(),
+            events: [systemInit('sess-1'), resultEventSuccess()],
+            exitCode: 0,
+            timedOut: false,
+            stderr: '',
+        });
+        const invoker = createCursorAgentInvoker(baseInvokerConfig({ heartbeatIntervalMs: 10 }));
+        const result = await invoker({ command: '/gsd/execute-plan', args: '/p', description: 'x' }, '/workspace', logger, { goalTitle: 'Goal', phaseNumber: 3, planNumber: 1 });
+        expect(result).toEqual({ success: true, output: 'ok' });
+        expect(appendSessionLogMock).toHaveBeenCalled();
+        const statuses = appendSessionLogMock.mock.calls.map((c) => c[1]?.status);
+        expect(statuses[0]).toBe('running');
+        expect(statuses[1]).toBe('done');
+        expect(appendSessionLogMock.mock.calls[1][1]).toMatchObject({
+            status: 'done',
+            sessionId: 'sess-1',
+            durationMs: expect.any(Number),
+        });
+    });
+    it('writes timeout status when runAgent timedOut is true', async () => {
+        runAgentMock.mockResolvedValue({
+            sessionId: 'sess-2',
+            resultEvent: null,
+            events: [systemInit('sess-2')],
+            exitCode: null,
+            timedOut: true,
+            stderr: 'some stderr',
+        });
+        const invoker = createCursorAgentInvoker(baseInvokerConfig());
+        const result = await invoker({ command: '/gsd/execute-plan', args: '/p', description: 'x' }, '/workspace', logger, { goalTitle: 'Goal', phaseNumber: 3, planNumber: 1 });
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('timed out');
+        const statuses = appendSessionLogMock.mock.calls.map((c) => c[1]?.status);
+        expect(statuses).toEqual(['running', 'timeout']);
+    });
+    it('writes crashed status when agent exits non-zero without timeout', async () => {
+        runAgentMock.mockResolvedValue({
+            sessionId: 'sess-3',
+            resultEvent: null,
+            events: [systemInit('sess-3')],
+            exitCode: 130,
+            timedOut: false,
+            stderr: 'Aborting operation...\n',
+        });
+        const invoker = createCursorAgentInvoker(baseInvokerConfig());
+        const result = await invoker({ command: '/gsd/execute-plan', args: '/p', description: 'x' }, '/workspace', logger, { goalTitle: 'Goal', phaseNumber: 3, planNumber: 1 });
+        expect(result.success).toBe(false);
+        expect(result.error).toContain('exit 130');
+        const statuses = appendSessionLogMock.mock.calls.map((c) => c[1]?.status);
+        expect(statuses).toEqual(['running', 'crashed']);
+        expect(appendSessionLogMock.mock.calls[1][1]).toMatchObject({
+            status: 'crashed',
+            sessionId: 'sess-3',
+            error: expect.any(String),
+        });
+    });
+    it('heartbeat writes at least once and is unlinked on completion', async () => {
+        vi.useFakeTimers();
+        runAgentMock.mockImplementation(async (opts) => {
+            opts.onEvent?.(systemInit('sess-4'));
+            return {
+                sessionId: 'sess-4',
+                resultEvent: resultEventSuccess(),
+                events: [systemInit('sess-4'), resultEventSuccess()],
+                exitCode: 0,
+                timedOut: false,
+                stderr: '',
+            };
+        });
+        const invoker = createCursorAgentInvoker(baseInvokerConfig({ heartbeatIntervalMs: 10 }));
+        const promise = invoker({ command: '/gsd/execute-plan', args: '/p', description: 'x' }, '/workspace', logger, { goalTitle: 'Goal', phaseNumber: 3, planNumber: 1 });
+        // allow initial tick + at least one interval tick
+        await vi.advanceTimersByTimeAsync(15);
+        const result = await promise;
+        expect(result.success).toBe(true);
+        expect(writeFileMock).toHaveBeenCalled();
+        expect(unlinkMock).toHaveBeenCalledWith('/tmp/heartbeat.txt');
+    });
+});