gsd-unsupervised 1.0.0

package/dist/resource-governor.d.ts

@@ -0,0 +1,54 @@
+export interface LoadInfo {
+    load1: number;
+    load5: number;
+    load15: number;
+    cpuCount: number;
+    /**
+     * Approximate fraction of total CPU capacity used, based on 1-minute load
+     * average divided by logical CPU count. This is a heuristic, not a precise
+     * utilization metric, but is stable and cheap to compute.
+     */
+    cpuFraction: number;
+    /**
+     * Approximate fraction of total system memory in use, based on
+     * (total - free) / total from `os.totalmem()` / `os.freemem()`.
+     */
+    memoryFraction: number;
+    totalMemBytes: number;
+    freeMemBytes: number;
+}
+export interface WaitForHeadroomOptions {
+    /**
+     * Maximum allowed CPU fraction before new agent work is allowed to start.
+     * 1.0 means 100% of all logical CPUs; 0.75 (default) means ~75% of total.
+     */
+    maxCpuFraction: number;
+    /**
+     * Maximum allowed memory fraction before new agent work is allowed to start.
+     * 1.0 means 100% of total RAM; 0.9 (default) means ~90%.
+     */
+    maxMemoryFraction?: number;
+    /**
+     * Minimum delay between load checks while waiting for headroom.
+     * Defaults to 2s to avoid busy-waiting.
+     */
+    pollIntervalMs?: number;
+    /**
+     * Optional absolute upper bound on wait time. When exceeded, the function
+     * resolves anyway so the daemon cannot deadlock if the machine is saturated.
+     * Defaults to 2 minutes.
+     */
+    maxWaitMs?: number;
+    /**
+     * Optional logger interface (subset of pino) used for structured logging.
+     */
+    logger?: {
+        debug: (obj: unknown, msg?: string) => void;
+        warn: (obj: unknown, msg?: string) => void;
+    };
+}
+export declare function currentLoadInfo(maxCpuFraction?: number, maxMemoryFraction?: number): LoadInfo & {
+    maxCpuFraction?: number;
+    maxMemoryFraction?: number;
+};
+export declare function waitForHeadroom(options: WaitForHeadroomOptions): Promise<void>;

package/dist/resource-governor.js

@@ -0,0 +1,57 @@
+import os from 'node:os';
+export function currentLoadInfo(maxCpuFraction, maxMemoryFraction) {
+    const [load1, load5, load15] = os.loadavg();
+    const cpuCount = Math.max(os.cpus()?.length ?? 1, 1);
+    const cpuFraction = cpuCount > 0 ? load1 / cpuCount : 0;
+    const totalMemBytes = os.totalmem();
+    const freeMemBytes = os.freemem();
+    const memoryFraction = totalMemBytes > 0 ? (totalMemBytes - freeMemBytes) / totalMemBytes : 0;
+    return {
+        load1,
+        load5,
+        load15,
+        cpuCount,
+        cpuFraction,
+        memoryFraction,
+        totalMemBytes,
+        freeMemBytes,
+        maxCpuFraction,
+        maxMemoryFraction,
+    };
+}
+export async function waitForHeadroom(options) {
+    const { maxCpuFraction, maxMemoryFraction, pollIntervalMs = 2000, maxWaitMs = 120_000, logger, } = options;
+    // Treat thresholds >= 1 as "no gating" for that resource to keep tests
+    // and opt-out configurations fast.
+    const validCpu = maxCpuFraction !== undefined && maxCpuFraction > 0 && maxCpuFraction < 1;
+    const validMem = maxMemoryFraction !== undefined && maxMemoryFraction > 0 && maxMemoryFraction < 1;
+    if (!validCpu && !validMem) {
+        // Misconfiguration — do not block orchestration, just log once and return.
+        logger?.warn({ maxCpuFraction, maxMemoryFraction }, 'resource-governor: invalid thresholds, skipping headroom check');
+        return;
+    }
+    const start = Date.now();
+    // First, allow a cheap fast-path so we don't sleep when there's plenty of headroom.
+    let info = currentLoadInfo(maxCpuFraction, maxMemoryFraction);
+    const withinCpu = !validCpu || info.cpuFraction <= maxCpuFraction;
+    const withinMem = !validMem || info.memoryFraction <= maxMemoryFraction;
+    if (withinCpu && withinMem) {
+        logger?.debug({ load: info }, 'resource-governor: sufficient CPU headroom, proceeding immediately');
+        return;
+    }
+    logger?.warn({ load: info }, 'resource-governor: high system load detected, waiting for headroom');
+    // Slow-path: periodically poll until below threshold or timeout expires.
+    while ((!validCpu || info.cpuFraction > maxCpuFraction) ||
+        (!validMem || info.memoryFraction > maxMemoryFraction)) {
+        const elapsed = Date.now() - start;
+        if (elapsed >= maxWaitMs) {
+            logger?.warn({ load: info, elapsedMs: elapsed, maxWaitMs }, 'resource-governor: max wait exceeded, proceeding despite high load');
+            return;
+        }
+        const remainingMs = maxWaitMs - elapsed;
+        const delayMs = Math.min(pollIntervalMs, remainingMs);
+        await new Promise((resolve) => setTimeout(resolve, delayMs));
+        info = currentLoadInfo(maxCpuFraction, maxMemoryFraction);
+    }
+    logger?.debug({ load: info, waitedMs: Date.now() - start }, 'resource-governor: CPU headroom restored, resuming work');
+}

package/dist/resource-governor.test.d.ts

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

package/dist/resource-governor.test.js

@@ -0,0 +1,33 @@
+import { describe, it, expect, vi } from 'vitest';
+import { currentLoadInfo, waitForHeadroom } from './resource-governor.js';
+describe('resource-governor', () => {
+    it('returns sane currentLoadInfo shape', () => {
+        const info = currentLoadInfo();
+        expect(typeof info.load1).toBe('number');
+        expect(typeof info.load5).toBe('number');
+        expect(typeof info.load15).toBe('number');
+        expect(typeof info.cpuCount).toBe('number');
+        expect(typeof info.cpuFraction).toBe('number');
+        expect(info.cpuCount).toBeGreaterThan(0);
+    });
+    it('waitForHeadroom resolves quickly when load is already below threshold', async () => {
+        const logger = { debug: vi.fn(), warn: vi.fn() };
+        await expect(waitForHeadroom({
+            maxCpuFraction: 0.99,
+            pollIntervalMs: 10,
+            maxWaitMs: 1000,
+            logger,
+        })).resolves.toBeUndefined();
+    });
+    it('waitForHeadroom does not throw on invalid config', async () => {
+        const logger = { debug: vi.fn(), warn: vi.fn() };
+        await expect(waitForHeadroom({
+            // Invalid (> 1) but should not crash orchestration.
+            maxCpuFraction: 1.5,
+            pollIntervalMs: 10,
+            maxWaitMs: 50,
+            logger,
+        })).resolves.toBeUndefined();
+        expect(logger.warn).toHaveBeenCalled();
+    });
+});

package/dist/resume-pointer.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Pure computation of resume pointers from session log and STATE.md.
+ * Used by the daemon/orchestrator to resume from the last known successful
+ * phase/plan when a previous run was interrupted (crashed or running).
+ *
+ * This module has no side effects: it does not mutate files or start processes.
+ */
+/** Resume position for crash recovery. planNumber 0 means "first plan of this phase". */
+export interface ResumePointer {
+    phaseNumber: number;
+    planNumber: number;
+}
+export interface ComputeResumePointerOpts {
+    /** Path to the session log file (JSONL). */
+    sessionLogPath: string;
+    /** Path to STATE.md. */
+    stateMdPath: string;
+    /** First pending goal title; only entries matching this goal are considered. */
+    goalTitle: string;
+}
+/**
+ * Derives the last known successful execution point from the session log.
+ * Returns null when:
+ * - Session log or STATE is missing/unreadable
+ * - No plan-complete or phase-complete entries exist for the goal
+ * - The last entry for the goal is not running/crashed (run completed cleanly)
+ * - STATE disagrees with the log in a way that indicates inconsistency (conservative fallback)
+ *
+ * plan-complete = status 'done' and phase '/gsd/execute-plan' with phaseNumber and planNumber
+ * phase-complete = status 'done' and phase '/gsd/plan-phase' with phaseNumber
+ *
+ * When the last plan-complete is phase X plan Y, the pointer is (X, Y+1) — resume at next plan.
+ * When the last phase-complete is phase X (no plan-complete in that phase), the pointer is (X+1, 0) — resume at first plan of next phase.
+ * planNumber 0 means "first plan of the indicated phase".
+ */
+export declare function computeResumePointer(opts: ComputeResumePointerOpts): Promise<ResumePointer | null>;

package/dist/resume-pointer.js

@@ -0,0 +1,116 @@
+/**
+ * Pure computation of resume pointers from session log and STATE.md.
+ * Used by the daemon/orchestrator to resume from the last known successful
+ * phase/plan when a previous run was interrupted (crashed or running).
+ *
+ * This module has no side effects: it does not mutate files or start processes.
+ */
+import { readSessionLog } from './session-log.js';
+import { readStateMd } from './state-parser.js';
+/**
+ * Derives the last known successful execution point from the session log.
+ * Returns null when:
+ * - Session log or STATE is missing/unreadable
+ * - No plan-complete or phase-complete entries exist for the goal
+ * - The last entry for the goal is not running/crashed (run completed cleanly)
+ * - STATE disagrees with the log in a way that indicates inconsistency (conservative fallback)
+ *
+ * plan-complete = status 'done' and phase '/gsd/execute-plan' with phaseNumber and planNumber
+ * phase-complete = status 'done' and phase '/gsd/plan-phase' with phaseNumber
+ *
+ * When the last plan-complete is phase X plan Y, the pointer is (X, Y+1) — resume at next plan.
+ * When the last phase-complete is phase X (no plan-complete in that phase), the pointer is (X+1, 0) — resume at first plan of next phase.
+ * planNumber 0 means "first plan of the indicated phase".
+ */
+export async function computeResumePointer(opts) {
+    const { sessionLogPath, stateMdPath, goalTitle } = opts;
+    const goalTrim = goalTitle.trim();
+    if (!goalTrim)
+        return null;
+    const entries = await readSessionLog(sessionLogPath);
+    if (entries.length === 0)
+        return null;
+    const stateSnapshot = await readStateMd(stateMdPath);
+    // Filter entries for this goal
+    const goalEntries = entries.filter((e) => (e.goalTitle ?? '').trim() === goalTrim);
+    if (goalEntries.length === 0)
+        return null;
+    // Only resume when the last entry for this goal is running or crashed
+    const lastForGoal = goalEntries[goalEntries.length - 1];
+    if (lastForGoal.status !== 'running' && lastForGoal.status !== 'crashed') {
+        return null;
+    }
+    // Find last plan-complete (done + execute-plan with phaseNumber and planNumber)
+    const planComplete = findLastPlanComplete(goalEntries);
+    const phaseComplete = findLastPhaseComplete(goalEntries);
+    let pointer = null;
+    if (planComplete) {
+        // Resume at next plan in same phase
+        pointer = {
+            phaseNumber: planComplete.phaseNumber,
+            planNumber: (planComplete.planNumber ?? 0) + 1,
+        };
+    }
+    else if (phaseComplete) {
+        // Resume at first plan of next phase
+        pointer = {
+            phaseNumber: (phaseComplete.phaseNumber ?? 0) + 1,
+            planNumber: 0,
+        };
+    }
+    if (!pointer)
+        return null;
+    // Cross-check STATE: if STATE shows a phase in progress but we have no corresponding
+    // completion in the log, favor the more conservative (earlier) pointer
+    if (stateSnapshot) {
+        const statePhase = stateSnapshot.phaseNumber;
+        const statePlan = stateSnapshot.planNumber;
+        const statusLower = stateSnapshot.status.toLowerCase();
+        // STATE says we're in a phase with plans, but our pointer is ahead — be conservative
+        if (pointer.phaseNumber > statePhase ||
+            (pointer.phaseNumber === statePhase && pointer.planNumber > statePlan && statePlan > 0)) {
+            // STATE might be stale; if status suggests "in progress", use STATE as ceiling
+            if (statusLower.includes('executing') ||
+                statusLower.includes('planned') ||
+                statusLower.includes('resuming')) {
+                if (statePhase < pointer.phaseNumber) {
+                    pointer = { phaseNumber: statePhase, planNumber: statePlan > 0 ? statePlan : 0 };
+                }
+                else if (statePhase === pointer.phaseNumber && statePlan > 0 && pointer.planNumber > statePlan) {
+                    pointer = { phaseNumber: statePhase, planNumber: statePlan };
+                }
+            }
+        }
+    }
+    if (pointer.phaseNumber < 1)
+        return null;
+    if (pointer.planNumber < 0)
+        return null;
+    return pointer;
+}
+function findLastPlanComplete(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.status === 'done' &&
+            e.phase === '/gsd/execute-plan' &&
+            typeof e.phaseNumber === 'number' &&
+            e.phaseNumber >= 1 &&
+            typeof e.planNumber === 'number' &&
+            e.planNumber >= 1) {
+            return e;
+        }
+    }
+    return null;
+}
+function findLastPhaseComplete(entries) {
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const e = entries[i];
+        if (e.status === 'done' &&
+            e.phase === '/gsd/plan-phase' &&
+            typeof e.phaseNumber === 'number' &&
+            e.phaseNumber >= 1) {
+            return e;
+        }
+    }
+    return null;
+}

package/dist/roadmap-parser.d.ts

@@ -0,0 +1,24 @@
+export interface PhaseInfo {
+    number: number;
+    name: string;
+    description: string;
+    dirName: string;
+    complete: boolean;
+}
+export interface PlanInfo {
+    phaseNumber: number;
+    planNumber: number;
+    planPath: string;
+    summaryPath: string;
+    executed: boolean;
+}
+export declare function parseRoadmap(roadmapPath: string): Promise<PhaseInfo[]>;
+export declare function findPhaseDir(phasesRoot: string, phaseNumber: number): string | null;
+export declare function discoverPlans(phaseDir: string): Promise<PlanInfo[]>;
+export declare function getNextUnexecutedPlan(plans: PlanInfo[]): PlanInfo | null;
+export declare function isPhaseComplete(plans: PlanInfo[]): boolean;
+/**
+ * Returns true iff the plan's SUMMARY file exists (auditable plan completion).
+ * Same heuristic as discoverPlans: plan XX-N-PLAN.md → XX-N-SUMMARY.md (N may be zero-padded).
+ */
+export declare function isPlanCompleted(phaseDir: string, planNumber: number): boolean;

package/dist/roadmap-parser.js

@@ -0,0 +1,105 @@
+import { readFile, readdir } from 'node:fs/promises';
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+const PHASE_RE = /^- \[([ xX])\] \*\*Phase (\d+(?:\.\d+)?): (.+?)\*\* — (.+)$/;
+const PLAN_FILE_RE = /^(\d+(?:\.\d+)?)-(\d+)-PLAN\.md$/;
+function phaseNumberToPrefix(phaseNumber) {
+    if (Number.isInteger(phaseNumber)) {
+        return String(phaseNumber).padStart(2, '0');
+    }
+    const [intPart, decPart] = String(phaseNumber).split('.');
+    return `${intPart.padStart(2, '0')}.${decPart}`;
+}
+export async function parseRoadmap(roadmapPath) {
+    let content;
+    try {
+        content = await readFile(roadmapPath, 'utf-8');
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            throw new Error(`Roadmap file not found: ${roadmapPath}`);
+        }
+        throw err;
+    }
+    if (content.trim().length === 0)
+        return [];
+    const lines = content.replace(/\r\n/g, '\n').split('\n');
+    const phases = [];
+    for (const line of lines) {
+        const match = line.match(PHASE_RE);
+        if (!match)
+            continue;
+        const complete = match[1] === 'x' || match[1] === 'X';
+        const number = parseFloat(match[2]);
+        const name = match[3];
+        const description = match[4];
+        const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+        const dirName = `${phaseNumberToPrefix(number)}-${slug}`;
+        phases.push({ number, name, description, dirName, complete });
+    }
+    phases.sort((a, b) => a.number - b.number);
+    return phases;
+}
+export function findPhaseDir(phasesRoot, phaseNumber) {
+    if (!existsSync(phasesRoot))
+        return null;
+    const prefix = phaseNumberToPrefix(phaseNumber) + '-';
+    let entries;
+    try {
+        entries = readdirSync(phasesRoot, { withFileTypes: true })
+            .filter((d) => d.isDirectory())
+            .map((d) => d.name);
+    }
+    catch {
+        return null;
+    }
+    const match = entries.find((name) => name.startsWith(prefix));
+    return match ? join(phasesRoot, match) : null;
+}
+export async function discoverPlans(phaseDir) {
+    let entries;
+    try {
+        entries = await readdir(phaseDir);
+    }
+    catch (err) {
+        if (err instanceof Error && 'code' in err && err.code === 'ENOENT') {
+            throw new Error(`Phase directory not found: ${phaseDir}`);
+        }
+        throw err;
+    }
+    const plans = [];
+    for (const entry of entries) {
+        const match = entry.match(PLAN_FILE_RE);
+        if (!match)
+            continue;
+        const phaseNumber = parseFloat(match[1]);
+        const planNumber = parseInt(match[2], 10);
+        const planPath = join(phaseDir, entry);
+        const summaryFile = entry.replace('-PLAN.md', '-SUMMARY.md');
+        const summaryPath = join(phaseDir, summaryFile);
+        const executed = existsSync(summaryPath);
+        plans.push({ phaseNumber, planNumber, planPath, summaryPath, executed });
+    }
+    plans.sort((a, b) => a.planNumber - b.planNumber);
+    return plans;
+}
+export function getNextUnexecutedPlan(plans) {
+    return plans.find((p) => !p.executed) ?? null;
+}
+export function isPhaseComplete(plans) {
+    return plans.length > 0 && plans.every((p) => p.executed);
+}
+/**
+ * Returns true iff the plan's SUMMARY file exists (auditable plan completion).
+ * Same heuristic as discoverPlans: plan XX-N-PLAN.md → XX-N-SUMMARY.md (N may be zero-padded).
+ */
+export function isPlanCompleted(phaseDir, planNumber) {
+    const plans = readdirSync(phaseDir);
+    const summarySuffixRe = new RegExp(`-(\\d+)-SUMMARY\\.md$`);
+    return plans.some((name) => {
+        const m = name.match(summarySuffixRe);
+        if (!m)
+            return false;
+        return parseInt(m[1], 10) === planNumber && existsSync(join(phaseDir, name));
+    });
+}

package/dist/roadmap-parser.test.d.ts

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

package/dist/roadmap-parser.test.js

@@ -0,0 +1,57 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { findPhaseDir, discoverPlans, isPlanCompleted } from './roadmap-parser.js';
+describe('roadmap-parser', () => {
+    let phasesRoot;
+    let phaseDir;
+    beforeEach(() => {
+        phasesRoot = mkdtempSync(join(tmpdir(), 'roadmap-test-'));
+        phaseDir = join(phasesRoot, '05-crash-detection-recovery');
+        mkdirSync(phaseDir, { recursive: true });
+    });
+    afterEach(() => {
+        try {
+            rmSync(phasesRoot, { recursive: true });
+        }
+        catch {
+            // ignore
+        }
+    });
+    describe('isPlanCompleted', () => {
+        it('returns true when SUMMARY exists for plan number', () => {
+            writeFileSync(join(phaseDir, '05-01-PLAN.md'), '# Plan', 'utf-8');
+            writeFileSync(join(phaseDir, '05-01-SUMMARY.md'), '# Summary', 'utf-8');
+            expect(isPlanCompleted(phaseDir, 1)).toBe(true);
+        });
+        it('returns false when only PLAN exists', () => {
+            writeFileSync(join(phaseDir, '05-01-PLAN.md'), '# Plan', 'utf-8');
+            expect(isPlanCompleted(phaseDir, 1)).toBe(false);
+        });
+        it('returns false when SUMMARY does not exist for plan number', () => {
+            writeFileSync(join(phaseDir, '05-02-PLAN.md'), '# Plan', 'utf-8');
+            expect(isPlanCompleted(phaseDir, 2)).toBe(false);
+        });
+        it('returns true for plan 2 when 05-02-SUMMARY.md exists', () => {
+            writeFileSync(join(phaseDir, '05-02-PLAN.md'), '# Plan', 'utf-8');
+            writeFileSync(join(phaseDir, '05-02-SUMMARY.md'), '# Summary', 'utf-8');
+            expect(isPlanCompleted(phaseDir, 2)).toBe(true);
+        });
+    });
+    describe('findPhaseDir and discoverPlans', () => {
+        it('findPhaseDir finds phase directory by number', () => {
+            const dir = findPhaseDir(phasesRoot, 5);
+            expect(dir).toBe(phaseDir);
+        });
+        it('discoverPlans marks executed when SUMMARY exists', async () => {
+            writeFileSync(join(phaseDir, '05-01-PLAN.md'), '', 'utf-8');
+            writeFileSync(join(phaseDir, '05-01-SUMMARY.md'), '', 'utf-8');
+            writeFileSync(join(phaseDir, '05-02-PLAN.md'), '', 'utf-8');
+            const plans = await discoverPlans(phaseDir);
+            expect(plans).toHaveLength(2);
+            expect(plans[0].executed).toBe(true);
+            expect(plans[1].executed).toBe(false);
+        });
+    });
+});

package/dist/session-log.d.ts

@@ -0,0 +1,53 @@
+/** Context passed when invoking the agent for session log entries (goal/phase/plan). */
+export interface SessionLogContext {
+    goalTitle: string;
+    phaseNumber?: number;
+    planNumber?: number;
+}
+/**
+ * Session log schema (append-only, one JSON object per line).
+ * - timestamp: ISO string
+ * - goalTitle: string
+ * - phase: command label (e.g. /gsd/execute-plan)
+ * - phaseNumber, planNumber: optional; set when in phase/plan loop for crash recovery
+ * - sessionId: string | null
+ * - command: full command string
+ * - status: 'running' | 'done' | 'crashed' | 'timeout'
+ * - durationMs, error: optional
+ * No in-place edits; append only.
+ */
+export interface SessionLogEntry {
+    timestamp: string;
+    goalTitle: string;
+    phase: string;
+    phaseNumber?: number;
+    planNumber?: number;
+    sessionId: string | null;
+    command: string;
+    status: 'running' | 'done' | 'crashed' | 'timeout';
+    durationMs?: number;
+    error?: string;
+}
+export declare function appendSessionLog(logPath: string, entry: SessionLogEntry): Promise<void>;
+export declare function readSessionLog(logPath: string): Promise<SessionLogEntry[]>;
+/**
+ * Returns the last entry with status 'running'. Legacy alias for
+ * inspectForCrashedSessions when only 'running' is needed.
+ */
+export declare function getLastRunningSession(logPath: string): Promise<SessionLogEntry | null>;
+/**
+ * Returns the most recent entry if its status is 'running' or 'crashed', else null.
+ * Used for crash recovery to detect an interrupted session. Skips malformed lines.
+ */
+export declare function inspectForCrashedSessions(logPath: string): Promise<SessionLogEntry | null>;
+/** Resume position for crash recovery; only when unambiguous. */
+export interface ResumeFrom {
+    phaseNumber: number;
+    planNumber: number;
+}
+/**
+ * Computes a deterministic resume point when the last session was crashed or running.
+ * Returns null on ambiguity (empty log, goal mismatch, or missing phase/plan).
+ * Derives resume point from SUMMARY file existence via roadmap-parser, not from STATE.md.
+ */
+export declare function computeResumePoint(sessionLogPath: string, workspaceRoot: string, firstPendingGoalTitle: string): Promise<ResumeFrom | null>;

package/dist/session-log.js

@@ -0,0 +1,92 @@
+import { readFile, appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import path from 'node:path';
+import { parseRoadmap, findPhaseDir, discoverPlans, getNextUnexecutedPlan } from './roadmap-parser.js';
+export async function appendSessionLog(logPath, entry) {
+    const line = JSON.stringify(entry) + '\n';
+    try {
+        const dir = dirname(logPath);
+        if (dir && dir !== '.') {
+            await mkdir(dir, { recursive: true }).catch(() => { });
+        }
+        await appendFile(logPath, line, { encoding: 'utf-8', flag: 'a' });
+    }
+    catch {
+        // Best-effort only: logging failures must never crash the daemon.
+    }
+}
+export async function readSessionLog(logPath) {
+    let content;
+    try {
+        content = await readFile(logPath, 'utf-8');
+    }
+    catch {
+        // Missing or unreadable log is treated as "no history" for callers.
+        return [];
+    }
+    const entries = [];
+    for (const line of content.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        try {
+            entries.push(JSON.parse(trimmed));
+        }
+        catch {
+            // skip malformed lines
+        }
+    }
+    return entries;
+}
+/**
+ * Returns the last entry with status 'running'. Legacy alias for
+ * inspectForCrashedSessions when only 'running' is needed.
+ */
+export async function getLastRunningSession(logPath) {
+    const entries = await readSessionLog(logPath);
+    for (let i = entries.length - 1; i >= 0; i--) {
+        if (entries[i].status === 'running') {
+            return entries[i];
+        }
+    }
+    return null;
+}
+/**
+ * Returns the most recent entry if its status is 'running' or 'crashed', else null.
+ * Used for crash recovery to detect an interrupted session. Skips malformed lines.
+ */
+export async function inspectForCrashedSessions(logPath) {
+    const entries = await readSessionLog(logPath);
+    if (entries.length === 0)
+        return null;
+    const last = entries[entries.length - 1];
+    return last.status === 'running' || last.status === 'crashed' ? last : null;
+}
+/**
+ * Computes a deterministic resume point when the last session was crashed or running.
+ * Returns null on ambiguity (empty log, goal mismatch, or missing phase/plan).
+ * Derives resume point from SUMMARY file existence via roadmap-parser, not from STATE.md.
+ */
+export async function computeResumePoint(sessionLogPath, workspaceRoot, firstPendingGoalTitle) {
+    const entry = await inspectForCrashedSessions(sessionLogPath);
+    const goalTrim = firstPendingGoalTitle.trim();
+    if (!entry || !goalTrim)
+        return null;
+    if (entry.goalTitle.trim() !== goalTrim)
+        return null;
+    const roadmapPath = path.join(workspaceRoot, '.planning', 'ROADMAP.md');
+    const phasesRoot = path.join(workspaceRoot, '.planning', 'phases');
+    const phases = await parseRoadmap(roadmapPath);
+    for (let i = 0; i < phases.length; i++) {
+        const phase = phases[i];
+        const phaseDir = findPhaseDir(phasesRoot, phase.number);
+        if (!phaseDir)
+            continue;
+        const plans = await discoverPlans(phaseDir);
+        const next = getNextUnexecutedPlan(plans);
+        if (next) {
+            return { phaseNumber: i + 1, planNumber: next.planNumber };
+        }
+    }
+    return null;
+}

package/dist/session-log.test.d.ts

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