gsd-unsupervised 1.0.0

package/dist/cursor-agent.js

@@ -0,0 +1,156 @@
+import path from 'node:path';
+import { writeFile, unlink } from 'node:fs/promises';
+import { runAgent } from './agent-runner.js';
+import { appendSessionLog, } from './session-log.js';
+import { getCursorBinaryPath } from './config/paths.js';
+export function createCursorAgentInvoker(agentConfig) {
+    return async (command, workspaceDir, logger, logContext) => {
+        const cmdString = command.args
+            ? `${command.command} ${command.args}`
+            : command.command;
+        const prompt = 'Execute in non-interactive/YOLO mode. Auto-approve all confirmations. ' +
+            'Do not ask the user any questions — make reasonable decisions autonomously.\n\n' +
+            cmdString;
+        logger.info({ command: cmdString }, `Invoking cursor-agent: ${cmdString}`);
+        const baseEntry = {
+            timestamp: new Date().toISOString(),
+            goalTitle: logContext?.goalTitle ?? '',
+            phase: command.command,
+            phaseNumber: logContext?.phaseNumber,
+            planNumber: logContext?.planNumber,
+            sessionId: null,
+            command: cmdString,
+        };
+        await appendSessionLog(agentConfig.sessionLogPath, {
+            ...baseEntry,
+            status: 'running',
+        });
+        const startMs = Date.now();
+        const heartbeatPath = agentConfig.heartbeatPath;
+        const heartbeatIntervalMs = agentConfig.heartbeatIntervalMs ?? 15_000;
+        let heartbeatTimer = null;
+        const stopHeartbeat = async () => {
+            if (heartbeatTimer) {
+                clearInterval(heartbeatTimer);
+                heartbeatTimer = null;
+            }
+            if (heartbeatPath) {
+                try {
+                    await unlink(heartbeatPath);
+                }
+                catch {
+                    // ignore
+                }
+            }
+        };
+        if (heartbeatPath) {
+            const tick = () => {
+                writeFile(heartbeatPath, new Date().toISOString(), 'utf-8').catch(() => { });
+            };
+            tick();
+            heartbeatTimer = setInterval(tick, heartbeatIntervalMs);
+        }
+        try {
+            const result = await runAgent({
+                agentPath: agentConfig.agentPath,
+                workspace: workspaceDir,
+                prompt,
+                env: process.env.CURSOR_API_KEY
+                    ? { CURSOR_API_KEY: process.env.CURSOR_API_KEY }
+                    : undefined,
+                timeoutMs: agentConfig.defaultTimeoutMs,
+                onEvent: (event) => {
+                    if (event.type === 'system' && event.subtype === 'init') {
+                        logger.info({ sessionId: event.session_id }, 'Agent session started');
+                    }
+                    else if (event.type === 'tool_call') {
+                        logger.debug({ toolName: event.tool_call.name, callId: event.call_id }, `Tool call: ${event.tool_call.name}`);
+                    }
+                    else if (event.type === 'result') {
+                        logger.info({ isError: event.is_error, durationMs: event.duration_ms }, `Agent result: ${event.is_error ? 'error' : 'success'}`);
+                    }
+                },
+            });
+            const durationMs = Date.now() - startMs;
+            const timedOut = result.timedOut;
+            await stopHeartbeat();
+            if (timedOut) {
+                await appendSessionLog(agentConfig.sessionLogPath, {
+                    ...baseEntry,
+                    sessionId: result.sessionId,
+                    status: 'timeout',
+                    durationMs,
+                    error: `Agent timed out after ${agentConfig.defaultTimeoutMs}ms`,
+                });
+                return {
+                    success: false,
+                    error: `Agent timed out after ${agentConfig.defaultTimeoutMs}ms`,
+                };
+            }
+            if (result.exitCode === 0 && result.resultEvent) {
+                await appendSessionLog(agentConfig.sessionLogPath, {
+                    ...baseEntry,
+                    sessionId: result.sessionId,
+                    status: 'done',
+                    durationMs,
+                });
+                return { success: true, output: result.resultEvent.result };
+            }
+            const stderrSnippet = result.stderr.slice(0, 500);
+            const errorMsg = result.resultEvent?.is_error
+                ? `Agent error: ${result.resultEvent.result}`
+                : `Agent failed (exit ${result.exitCode})${stderrSnippet ? `: ${stderrSnippet}` : ''}`;
+            await appendSessionLog(agentConfig.sessionLogPath, {
+                ...baseEntry,
+                sessionId: result.sessionId,
+                status: 'crashed',
+                durationMs,
+                error: errorMsg,
+            });
+            return { success: false, error: errorMsg };
+        }
+        catch (err) {
+            await stopHeartbeat();
+            const durationMs = Date.now() - startMs;
+            const message = err instanceof Error ? err.message : String(err);
+            await appendSessionLog(agentConfig.sessionLogPath, {
+                ...baseEntry,
+                status: 'crashed',
+                durationMs,
+                error: message,
+            }).catch(() => { });
+            return { success: false, error: `Agent invocation failed: ${message}` };
+        }
+    };
+}
+export function validateCursorApiKey() {
+    const key = process.env.CURSOR_API_KEY;
+    if (!key || key.trim() === '') {
+        throw new Error('CURSOR_API_KEY environment variable is not set or empty.\n' +
+            'Set CURSOR_API_KEY environment variable. Generate from Cursor Dashboard → Cloud Agents → User API Keys.');
+    }
+}
+/** Agent-agnostic factory: returns the appropriate invoker for the given agent ID. */
+export function createAgentInvoker(agentId, config) {
+    switch (agentId) {
+        case 'cursor':
+            return createCursorAgentInvoker({
+                agentPath: getCursorBinaryPath(config),
+                defaultTimeoutMs: config.agentTimeoutMs,
+                sessionLogPath: config.sessionLogPath,
+                heartbeatPath: path.join(config.workspaceRoot, '.planning', 'heartbeat.txt'),
+                heartbeatIntervalMs: 15_000,
+            });
+        case 'claude-code':
+        case 'gemini-cli':
+        case 'codex': {
+            // TODO: Implement real adapters when those agents support GSD NDJSON/heartbeat contract.
+            const stub = async (command, workspaceDir, logger, _logContext) => {
+                logger.info(`Stub (${agentId}): would invoke agent with "${command.command} ${command.args ?? ''}" in ${workspaceDir}`);
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                return { success: true, output: 'stub' };
+            };
+            return stub;
+        }
+    }
+}

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

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

package/dist/cursor-agent.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { createAgentInvoker } from './cursor-agent.js';
+import { initLogger } from './logger.js';
+const baseConfig = {
+    goalsPath: './goals.md',
+    parallel: false,
+    maxConcurrent: 3,
+    maxCpuFraction: 0.75,
+    verbose: false,
+    logLevel: 'info',
+    workspaceRoot: '/tmp/test',
+    agent: 'cursor',
+    cursorAgentPath: '/usr/bin/cursor-agent',
+    agentTimeoutMs: 60_000,
+    sessionLogPath: '/tmp/session-log.jsonl',
+    stateWatchDebounceMs: 500,
+    requireCleanGitBeforePlan: true,
+    autoCheckpoint: false,
+};
+describe('createAgentInvoker', () => {
+    const logger = initLogger({ level: 'silent', pretty: false });
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+    it('returns cursor adapter for agent cursor', () => {
+        const invoker = createAgentInvoker('cursor', baseConfig);
+        expect(invoker).toBeTypeOf('function');
+        expect(invoker.length).toBe(4); // command, workspaceDir, logger, logContext
+    });
+    it('returns non-throwing stub for claude-code', async () => {
+        const invoker = createAgentInvoker('claude-code', baseConfig);
+        const infoSpy = vi.spyOn(logger, 'info');
+        const result = await invoker({ command: '/gsd/execute-plan', args: 'foo', description: 'test' }, '/workspace', logger);
+        expect(result.success).toBe(true);
+        expect(result.output).toBe('stub');
+        expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining('Stub (claude-code)'));
+    });
+    it('returns non-throwing stub for gemini-cli', async () => {
+        const invoker = createAgentInvoker('gemini-cli', baseConfig);
+        const infoSpy = vi.spyOn(logger, 'info');
+        const result = await invoker({ command: '/gsd/plan-phase', args: '1', description: 'test' }, '/workspace', logger);
+        expect(result.success).toBe(true);
+        expect(result.output).toBe('stub');
+        expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining('Stub (gemini-cli)'));
+    });
+    it('returns non-throwing stub for codex', async () => {
+        const invoker = createAgentInvoker('codex', baseConfig);
+        const infoSpy = vi.spyOn(logger, 'info');
+        const result = await invoker({ command: '/gsd/new-project', description: 'test' }, '/workspace', logger);
+        expect(result.success).toBe(true);
+        expect(result.output).toBe('stub');
+        expect(infoSpy).toHaveBeenCalledWith(expect.stringContaining('Stub (codex)'));
+    });
+    it('stub adapters have same call signature as cursor', async () => {
+        const stubInvoker = createAgentInvoker('claude-code', baseConfig);
+        const result = await stubInvoker({ command: '/gsd/execute-plan', args: 'path', description: 'desc' }, '/workspace', logger, { goalTitle: 'Goal', phaseNumber: 1, planNumber: 1 });
+        expect(result).toMatchObject({ success: true, output: 'stub' });
+        expect(result.error).toBeUndefined();
+    });
+});

package/dist/daemon.d.ts

@@ -0,0 +1,17 @@
+import type { AutopilotConfig } from './config.js';
+import type { Logger } from './logger.js';
+/**
+ * Orchestration: queue + hot-reload + webhook + parallel pool.
+ *
+ * - Goals are loaded at start and can be hot-reloaded when goals.md changes
+ *   (chokidar); new pending goals are merged into the queue. Webhook (POST
+ *   /api/goals, /api/todos, Twilio POST /webhook/twilio) can add goals/todos
+ *   and push into the queue immediately.
+ * - Prioritization: buildExecutionPlan() orders by [priority:N] then original
+ *   order. parallelGroup/dependsOn are parsed but not used for scheduling.
+ * - Pool: up to maxConcurrent workers when parallel is enabled; single workspace
+ *   uses one mutex so only one goal runs at a time (phase-level parallel still
+ *   applies inside execute-phase). Multi-workspace would allow true parallel goals.
+ */
+export declare function runDaemon(config: AutopilotConfig, logger: Logger): Promise<void>;
+export declare function registerShutdownHandlers(logger: Logger): void;

package/dist/daemon.js

@@ -0,0 +1,374 @@
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { stat, writeFile } from 'node:fs/promises';
+import chokidar from 'chokidar';
+import { createChildLogger } from './logger.js';
+import { loadGoals, getPendingGoals, buildExecutionPlan } from './goals.js';
+import { orchestrateGoal } from './orchestrator.js';
+import { createAgentInvoker } from './cursor-agent.js';
+import { StateWatcher } from './state-watcher.js';
+import { inspectForCrashedSessions, appendSessionLog, } from './session-log.js';
+import { computeResumePointer } from './resume-pointer.js';
+import { createStatusServer, readPlanningConfig } from './status-server.js';
+import { sendSms } from './notifier.js';
+import { writeGsdState } from './gsd-state.js';
+import { addTodo } from './todos-api.js';
+let shuttingDown = false;
+async function updateState(config, update) {
+    if (!config.statePath)
+        return;
+    try {
+        await writeGsdState(config.workspaceRoot, update, config.statePath);
+    }
+    catch {
+        // best-effort
+    }
+}
+/**
+ * Orchestration: queue + hot-reload + webhook + parallel pool.
+ *
+ * - Goals are loaded at start and can be hot-reloaded when goals.md changes
+ *   (chokidar); new pending goals are merged into the queue. Webhook (POST
+ *   /api/goals, /api/todos, Twilio POST /webhook/twilio) can add goals/todos
+ *   and push into the queue immediately.
+ * - Prioritization: buildExecutionPlan() orders by [priority:N] then original
+ *   order. parallelGroup/dependsOn are parsed but not used for scheduling.
+ * - Pool: up to maxConcurrent workers when parallel is enabled; single workspace
+ *   uses one mutex so only one goal runs at a time (phase-level parallel still
+ *   applies inside execute-phase). Multi-workspace would allow true parallel goals.
+ */
+export async function runDaemon(config, logger) {
+    const goals = await loadGoals(config.goalsPath);
+    const pending = getPendingGoals(goals);
+    if (pending.length === 0) {
+        logger.info('No pending goals in queue');
+        return;
+    }
+    const plan = buildExecutionPlan(pending);
+    const queue = [...plan.ordered];
+    const running = new Set();
+    let wakeResolver = null;
+    const wake = () => {
+        if (wakeResolver) {
+            wakeResolver();
+            wakeResolver = null;
+        }
+    };
+    const waitForWake = (ms) => new Promise((resolve) => {
+        wakeResolver = resolve;
+        setTimeout(() => {
+            if (wakeResolver === resolve) {
+                wakeResolver = null;
+                resolve();
+            }
+        }, ms);
+    });
+    const addToQueue = (goal) => {
+        if (running.has(goal.title))
+            return;
+        if (queue.some((g) => g.title === goal.title))
+            return;
+        queue.push(goal);
+        wake();
+    };
+    const totalGoalsInitial = queue.length;
+    logger.info({ count: totalGoalsInitial }, `Found ${totalGoalsInitial} pending goals`);
+    await updateState(config, {
+        daemonPid: process.pid,
+        startedAt: new Date().toISOString(),
+    });
+    const heartbeatIntervalMs = 30_000;
+    const heartbeatTimer = config.statePath &&
+        setInterval(() => {
+            updateState(config, { lastHeartbeat: new Date().toISOString() }).catch(() => { });
+        }, heartbeatIntervalMs);
+    const agent = createAgentInvoker(config.agent, config);
+    const stateMdPath = path.join(config.workspaceRoot, '.planning', 'STATE.md');
+    const heartbeatPath = path.join(config.workspaceRoot, '.planning', 'heartbeat.txt');
+    const planningConfigPath = path.join(config.workspaceRoot, '.planning', 'config.json');
+    const heartbeatTimeoutMs = 60_000;
+    let effectiveParallel = config.parallel;
+    try {
+        const planning = await readPlanningConfig(planningConfigPath);
+        if (planning.parallelization?.enabled !== undefined) {
+            effectiveParallel = planning.parallelization.enabled;
+        }
+    }
+    catch {
+        // use config.parallel
+    }
+    const numWorkers = effectiveParallel ? config.maxConcurrent : 1;
+    if (effectiveParallel) {
+        logger.info({ maxConcurrent: config.maxConcurrent }, `Parallel mode: up to ${config.maxConcurrent} workers (single workspace => one goal at a time via mutex)`);
+    }
+    else {
+        logger.info('Sequential mode: processing goals one at a time');
+    }
+    let currentGoal = null;
+    let completedCount = 0;
+    let statusServerClose = null;
+    let ngrokClose = null;
+    const webhookOptions = {
+        goalsPath: config.goalsPath,
+        workspaceRoot: config.workspaceRoot,
+        onQueueGoal: addToQueue,
+        getRunningTitles: () => Array.from(running),
+        addTodo: (title, area) => addTodo(config.workspaceRoot, title, area ?? 'general'),
+    };
+    if (config.statusServerPort) {
+        const { close } = createStatusServer(config.statusServerPort, () => ({
+            running: !shuttingDown,
+            currentGoal: currentGoal ?? undefined,
+        }), {
+            stateMdPath,
+            sessionLogPath: config.sessionLogPath,
+            workspaceRoot: config.workspaceRoot,
+            planningConfigPath,
+            webhook: webhookOptions,
+        });
+        statusServerClose = close;
+        logger.info({ port: config.statusServerPort }, 'Status server listening');
+        if (config.ngrok) {
+            const port = config.statusServerPort;
+            const child = spawn('ngrok', ['http', String(port)], {
+                stdio: 'inherit',
+                shell: false,
+            });
+            child.on('error', (err) => {
+                logger.warn({ err, port }, 'ngrok failed to start');
+            });
+            child.on('exit', (code, signal) => {
+                if (!shuttingDown && (code !== 0 || signal)) {
+                    logger.info({ code, signal }, 'ngrok exited');
+                }
+            });
+            ngrokClose = () => new Promise((resolve) => {
+                if (!child.killed && child.pid) {
+                    child.once('exit', () => resolve());
+                    child.kill('SIGTERM');
+                }
+                else {
+                    resolve();
+                }
+            });
+            logger.info({ port }, 'ngrok started (ngrok http %s)', port);
+        }
+    }
+    let resumeFrom = null;
+    if (queue.length > 0) {
+        const crashed = await inspectForCrashedSessions(config.sessionLogPath);
+        if (crashed?.status === 'running') {
+            try {
+                const st = await stat(heartbeatPath);
+                const ageMs = Date.now() - st.mtime.getTime();
+                if (ageMs > heartbeatTimeoutMs) {
+                    await appendSessionLog(config.sessionLogPath, {
+                        ...crashed,
+                        timestamp: new Date().toISOString(),
+                        status: 'crashed',
+                        error: `Heartbeat timeout (>${heartbeatTimeoutMs / 1000}s)`,
+                    });
+                }
+            }
+            catch {
+                await appendSessionLog(config.sessionLogPath, {
+                    ...crashed,
+                    timestamp: new Date().toISOString(),
+                    status: 'crashed',
+                    error: 'Heartbeat timeout (missing)',
+                });
+            }
+        }
+        resumeFrom = await computeResumePointer({
+            sessionLogPath: config.sessionLogPath,
+            stateMdPath,
+            goalTitle: queue[0]?.title ?? '',
+        });
+        if (resumeFrom) {
+            logger.info({ phaseNumber: resumeFrom.phaseNumber, planNumber: resumeFrom.planNumber }, 'Resuming from phase %s plan %s due to previous crash', resumeFrom.phaseNumber, resumeFrom.planNumber === 0 ? '1 (first)' : resumeFrom.planNumber);
+        }
+    }
+    const pauseFlagPath = path.join(config.workspaceRoot, '.pause-autopilot');
+    const goalsWatcher = chokidar.watch(config.goalsPath, { ignoreInitial: true });
+    goalsWatcher.on('change', async () => {
+        try {
+            const fresh = await loadGoals(config.goalsPath);
+            const newPending = getPendingGoals(fresh);
+            const newPlan = buildExecutionPlan(newPending);
+            for (const g of newPlan.ordered)
+                addToQueue(g);
+        }
+        catch (err) {
+            logger.warn({ err, path: config.goalsPath }, 'Hot-reload goals failed');
+        }
+    });
+    const workspaceMutex = (() => {
+        let locked = false;
+        const waiters = [];
+        return {
+            async run(fn) {
+                while (locked) {
+                    await new Promise((r) => waiters.push(r));
+                }
+                locked = true;
+                try {
+                    return await fn();
+                }
+                finally {
+                    locked = false;
+                    const next = waiters.shift();
+                    if (next)
+                        next();
+                }
+            },
+        };
+    })();
+    async function runOneGoal(goal, useResumeFrom) {
+        let plannedUpToPhaseNum = 0;
+        let currentResumeFrom = useResumeFrom;
+        let watcher = null;
+        try {
+            watcher = new StateWatcher({
+                stateMdPath,
+                debounceMs: config.stateWatchDebounceMs,
+                logger: createChildLogger(logger, 'state-watcher'),
+            });
+            watcher.on('state_changed', (payload) => {
+                logger.debug({
+                    phase: payload.current.phaseNumber,
+                    plan: payload.current.planNumber,
+                    status: payload.current.status,
+                }, 'state_changed');
+            });
+            watcher.on('phase_advanced', (p) => logger.info({ fromPhase: p.fromPhase, toPhase: p.toPhase, phaseName: p.phaseName }, 'phase_advanced'));
+            watcher.on('plan_advanced', (p) => logger.info({ phaseNumber: p.phaseNumber, fromPlan: p.fromPlan, toPlan: p.toPlan }, 'plan_advanced'));
+            watcher.on('phase_completed', (p) => logger.info({ phaseNumber: p.phaseNumber, phaseName: p.phaseName }, 'phase_completed'));
+            watcher.on('goal_completed', () => logger.info('goal_completed'));
+            watcher.start();
+        }
+        catch (err) {
+            logger.warn({ err, stateMdPath }, 'StateWatcher not started — proceeding without state watching');
+        }
+        try {
+            let attempt = 0;
+            while (attempt < 3) {
+                attempt++;
+                try {
+                    await orchestrateGoal({
+                        goal,
+                        config,
+                        logger,
+                        agent,
+                        isShuttingDown: () => shuttingDown,
+                        onProgress: (snapshot) => {
+                            if (snapshot.status.startsWith('Planned phase')) {
+                                plannedUpToPhaseNum = Math.max(plannedUpToPhaseNum, snapshot.phaseNumber);
+                            }
+                        },
+                        resumeFrom: currentResumeFrom,
+                        skipToPhase: attempt > 1 && plannedUpToPhaseNum > 0 ? plannedUpToPhaseNum + 1 : null,
+                    });
+                    break;
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    logger.error({ err, goal: goal.title, attempt, maxAttempts: 3 }, `Failed goal attempt ${attempt}/3: ${goal.title}`);
+                    if (attempt >= 3) {
+                        try {
+                            await writeFile(pauseFlagPath, `Paused after 3 failed attempts for goal: ${goal.title}\nLast error: ${msg}\n`, 'utf-8');
+                        }
+                        catch {
+                            // ignore
+                        }
+                        try {
+                            await sendSms(`GSD daemon paused after 3 retries.\nGoal: ${goal.title}\nError: ${msg}`);
+                        }
+                        catch (smsErr) {
+                            logger.warn({ err: smsErr }, 'SMS notification failed');
+                        }
+                        while (existsSync(pauseFlagPath) && !shuttingDown) {
+                            logger.info('Pause flag (.pause-autopilot) detected – sleeping 60s');
+                            await new Promise((r) => setTimeout(r, 60_000));
+                        }
+                    }
+                }
+                finally {
+                    currentResumeFrom = null;
+                }
+            }
+        }
+        finally {
+            if (watcher)
+                watcher.stop();
+        }
+    }
+    const runWorker = async () => {
+        while (!shuttingDown) {
+            while (existsSync(pauseFlagPath)) {
+                logger.info('Pause flag (.pause-autopilot) detected – sleeping 60s');
+                await new Promise((r) => setTimeout(r, 60_000));
+            }
+            const goal = queue.shift() ?? null;
+            if (!goal) {
+                if (running.size === 0)
+                    break;
+                await waitForWake(5000);
+                continue;
+            }
+            running.add(goal.title);
+            currentGoal = goal.title;
+            completedCount++;
+            const totalCount = completedCount + queue.length;
+            await updateState(config, { currentGoal: goal.title, progress: `${completedCount}/${totalCount}` });
+            if (shuttingDown) {
+                queue.unshift(goal);
+                running.delete(goal.title);
+                break;
+            }
+            logger.info({ goal: goal.title }, `Processing goal: ${goal.title}`);
+            const isFirst = completedCount === 1 && resumeFrom !== null;
+            await workspaceMutex.run(() => runOneGoal(goal, isFirst ? resumeFrom : null));
+            running.delete(goal.title);
+            currentGoal = null;
+            const progressStr = `${completedCount}/${completedCount + queue.length}`;
+            await updateState(config, {
+                lastGoalCompleted: goal.title,
+                progress: progressStr,
+                currentGoal: undefined,
+            });
+            logger.info({ goal: goal.title, progress: progressStr }, `Completed goal: ${goal.title}`);
+            wake();
+        }
+    };
+    await Promise.all(Array.from({ length: numWorkers }, () => runWorker()));
+    goalsWatcher.close();
+    if (heartbeatTimer) {
+        clearInterval(heartbeatTimer);
+    }
+    if (!shuttingDown) {
+        logger.info('All goals processed');
+    }
+    if (ngrokClose) {
+        await ngrokClose();
+    }
+    if (statusServerClose) {
+        await statusServerClose();
+    }
+}
+export function registerShutdownHandlers(logger) {
+    let signalCount = 0;
+    const handler = (signal) => {
+        signalCount++;
+        if (signalCount === 1) {
+            logger.info({ signal }, 'Shutting down gracefully...');
+            shuttingDown = true;
+        }
+        else {
+            logger.warn({ signal }, 'Forced shutdown');
+            process.exit(1);
+        }
+    };
+    process.on('SIGINT', () => handler('SIGINT'));
+    process.on('SIGTERM', () => handler('SIGTERM'));
+}

package/dist/git.d.ts

@@ -0,0 +1,23 @@
+/** One commit in the feed for dashboard/API. */
+export interface CommitEntry {
+    hash: string;
+    message: string;
+    timestamp: string;
+}
+/**
+ * Returns true if git working tree has no uncommitted changes (clean).
+ * Runs `git status --porcelain` in workspaceRoot; empty output = clean.
+ */
+export declare function isWorkingTreeClean(workspaceRoot: string, options?: {
+    ignorePaths?: string[];
+}): Promise<boolean>;
+/**
+ * Creates a checkpoint commit: git add -A && git commit -m message.
+ * Use when autoCheckpoint is true and tree is dirty before execute-plan.
+ */
+export declare function createCheckpoint(workspaceRoot: string, message: string): Promise<void>;
+/**
+ * Returns the last N commits (hash, message, timestamp) for dashboard/API.
+ * Uses simple-git. Returns [] on error or not a git repo.
+ */
+export declare function getRecentCommits(workspaceRoot: string, limit?: number): Promise<CommitEntry[]>;