bmalph 2.3.0 → 2.5.0

package/dist/utils/dryrun.js

@@ -11,6 +11,12 @@ export function logDryRunAction(action) {
         case "skip":
             console.log(`${prefix} Would skip: ${chalk.dim(action.path)}${action.reason ? ` (${action.reason})` : ""}`);
             break;
+        case "delete":
+            console.log(`${prefix} Would delete: ${chalk.red(action.path)}`);
+            break;
+        case "warn":
+            console.log(`${prefix} Warning: ${chalk.yellow(action.path)}${action.reason ? ` (${action.reason})` : ""}`);
+            break;
     }
 }
 export function formatDryRunSummary(actions) {
@@ -19,9 +25,18 @@ export function formatDryRunSummary(actions) {
     }
     const lines = [];
     lines.push(chalk.blue("\n[dry-run] Would perform the following actions:\n"));
+    const deletes = actions.filter((a) => a.type === "delete");
     const creates = actions.filter((a) => a.type === "create");
     const modifies = actions.filter((a) => a.type === "modify");
     const skips = actions.filter((a) => a.type === "skip");
+    const warns = actions.filter((a) => a.type === "warn");
+    if (deletes.length > 0) {
+        lines.push(chalk.red("Would delete:"));
+        for (const action of deletes) {
+            lines.push(`  ${action.path}`);
+        }
+        lines.push("");
+    }
     if (creates.length > 0) {
         lines.push(chalk.green("Would create:"));
         for (const action of creates) {
@@ -43,6 +58,13 @@ export function formatDryRunSummary(actions) {
         }
         lines.push("");
     }
+    if (warns.length > 0) {
+        lines.push(chalk.yellow("Warnings:"));
+        for (const action of warns) {
+            lines.push(`  ${action.path}${action.reason ? ` (${action.reason})` : ""}`);
+        }
+        lines.push("");
+    }
     lines.push(chalk.dim("No changes made."));
     return lines.join("\n");
 }

package/dist/utils/state.d.ts

@@ -21,6 +21,4 @@ export declare function readState(projectDir: string): Promise<BmalphState | nul
 export declare function writeState(projectDir: string, state: BmalphState): Promise<void>;
 export declare function getPhaseLabel(phase: number): string;
 export declare function getPhaseInfo(phase: number): PhaseInfo;
-/** @deprecated Use RalphLoopStatus from validate.ts instead */
-export type RalphStatus = RalphLoopStatus;
 export declare function readRalphStatus(projectDir: string): Promise<RalphLoopStatus>;

package/dist/utils/validate.js

@@ -176,6 +176,7 @@ const BASH_STATUS_MAP = {
     stopped: "blocked",
     completed: "completed",
     success: "completed",
+    graceful_exit: "completed",
 };
 export function normalizeRalphStatus(data) {
     assertObject(data, "normalizeRalphStatus");
@@ -185,8 +186,8 @@ export function normalizeRalphStatus(data) {
     return {
         loopCount,
         status,
-        tasksCompleted: 0,
-        tasksTotal: 0,
+        tasksCompleted: typeof data.tasks_completed === "number" ? data.tasks_completed : 0,
+        tasksTotal: typeof data.tasks_total === "number" ? data.tasks_total : 0,
     };
 }
 /**

package/dist/watch/dashboard.d.ts

@@ -0,0 +1,4 @@
+import type { WatchOptions } from "./types.js";
+export declare function createRefreshCallback(projectDir: string, write: (s: string) => void): () => Promise<void>;
+export declare function setupTerminal(): () => void;
+export declare function startDashboard(options: WatchOptions): Promise<void>;

package/dist/watch/dashboard.js

@@ -0,0 +1,60 @@
+import { readDashboardState } from "./state-reader.js";
+import { renderDashboard } from "./renderer.js";
+import { FileWatcher } from "./file-watcher.js";
+const CLEAR_SCREEN = "\x1B[2J\x1B[H";
+const HIDE_CURSOR = "\x1B[?25l";
+const SHOW_CURSOR = "\x1B[?25h";
+export function createRefreshCallback(projectDir, write) {
+    return async () => {
+        const state = await readDashboardState(projectDir);
+        const output = renderDashboard(state);
+        write(CLEAR_SCREEN + output + "\n");
+    };
+}
+export function setupTerminal() {
+    if (process.stdout.isTTY) {
+        process.stdout.write(HIDE_CURSOR);
+    }
+    return () => {
+        if (process.stdout.isTTY) {
+            process.stdout.write(SHOW_CURSOR);
+        }
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+            process.stdin.setRawMode(false);
+        }
+        process.stdin.pause();
+    };
+}
+export async function startDashboard(options) {
+    const { projectDir, interval } = options;
+    const cleanup = setupTerminal();
+    const refresh = createRefreshCallback(projectDir, (s) => process.stdout.write(s));
+    const watcher = new FileWatcher(refresh, interval);
+    return new Promise((resolve) => {
+        const stop = () => {
+            watcher.stop();
+            cleanup();
+            resolve();
+        };
+        if (process.stdin.isTTY && process.stdin.setRawMode) {
+            process.stdin.setRawMode(true);
+            process.stdin.resume();
+            process.stdin.setEncoding("utf-8");
+            process.stdin.on("data", (data) => {
+                if (data === "q" || data === "\x03") {
+                    stop();
+                }
+            });
+        }
+        const onResize = () => {
+            void refresh();
+        };
+        process.stdout.on("resize", onResize);
+        const onSignal = () => {
+            stop();
+        };
+        process.on("SIGINT", onSignal);
+        process.on("SIGTERM", onSignal);
+        watcher.start();
+    });
+}

package/dist/watch/file-watcher.d.ts

@@ -0,0 +1,9 @@
+export declare class FileWatcher {
+    private intervalId;
+    private readonly intervalMs;
+    private readonly callback;
+    constructor(callback: () => void | Promise<void>, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    private tick;
+}

package/dist/watch/file-watcher.js

@@ -0,0 +1,27 @@
+export class FileWatcher {
+    intervalId = null;
+    intervalMs;
+    callback;
+    constructor(callback, intervalMs = 2000) {
+        this.callback = callback;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        void this.tick();
+        this.intervalId = setInterval(() => void this.tick(), this.intervalMs);
+    }
+    stop() {
+        if (this.intervalId !== null) {
+            clearInterval(this.intervalId);
+            this.intervalId = null;
+        }
+    }
+    async tick() {
+        try {
+            await this.callback();
+        }
+        catch {
+            // Swallow errors to keep polling alive
+        }
+    }
+}

package/dist/watch/renderer.d.ts

@@ -0,0 +1,16 @@
+import type { DashboardState, LoopInfo, CircuitBreakerInfo, StoryProgress, AnalysisInfo, LogEntry, ExecutionProgress, SessionInfo } from "./types.js";
+export declare function padRight(str: string, len: number): string;
+export declare function progressBar(completed: number, total: number, width: number): string;
+export declare function formatSessionAge(createdAt: string): string;
+export declare function formatStatus(status: string): string;
+export declare function formatCBState(state: string): string;
+export declare function box(title: string, lines: string[], cols: number): string;
+export declare function renderHeader(cols: number): string;
+export declare function renderLoopPanel(loop: LoopInfo | null, execution: ExecutionProgress | null, session: SessionInfo | null, cols: number): string;
+export declare function renderCircuitBreakerPanel(cb: CircuitBreakerInfo | null, cols: number): string;
+export declare function renderStoriesPanel(stories: StoryProgress | null, cols: number): string;
+export declare function renderSideBySide(left: string, right: string, cols: number): string;
+export declare function renderAnalysisPanel(analysis: AnalysisInfo | null, cols: number): string;
+export declare function renderLogsPanel(logs: LogEntry[], cols: number): string;
+export declare function renderFooter(lastUpdated: Date, cols: number): string;
+export declare function renderDashboard(state: DashboardState, cols?: number): string;

package/dist/watch/renderer.js

@@ -0,0 +1,241 @@
+import chalk from "chalk";
+const BOX_CHARS = {
+    topLeft: "\u250C",
+    topRight: "\u2510",
+    bottomLeft: "\u2514",
+    bottomRight: "\u2518",
+    horizontal: "\u2500",
+    vertical: "\u2502",
+    headerLeft: "\u2554",
+    headerRight: "\u2557",
+    headerBottom: "\u255A",
+    headerBottomRight: "\u255D",
+    headerHoriz: "\u2550",
+    headerVert: "\u2551",
+};
+const PROGRESS_FILLED = "\u2588";
+const PROGRESS_EMPTY = "\u2591";
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\x1B\[\d+m/g;
+function stripAnsi(str) {
+    return str.replace(ANSI_PATTERN, "");
+}
+export function padRight(str, len) {
+    const visualLen = stripAnsi(str).length;
+    if (visualLen >= len) {
+        return str;
+    }
+    return str + " ".repeat(len - visualLen);
+}
+export function progressBar(completed, total, width) {
+    if (total <= 0) {
+        return PROGRESS_EMPTY.repeat(width);
+    }
+    const ratio = Math.min(completed / total, 1);
+    const filled = Math.round(ratio * width);
+    return chalk.green(PROGRESS_FILLED.repeat(filled)) + PROGRESS_EMPTY.repeat(width - filled);
+}
+export function formatSessionAge(createdAt) {
+    const now = Date.now();
+    const start = new Date(createdAt).getTime();
+    const diffSeconds = Math.max(0, Math.floor((now - start) / 1000));
+    const hours = Math.floor(diffSeconds / 3600);
+    const minutes = Math.floor((diffSeconds % 3600) / 60);
+    const seconds = diffSeconds % 60;
+    if (hours > 0) {
+        return `${String(hours)}h ${String(minutes)}m`;
+    }
+    return `${String(minutes)}m ${String(seconds)}s`;
+}
+export function formatStatus(status) {
+    switch (status) {
+        case "running":
+            return chalk.yellow(status);
+        case "completed":
+        case "success":
+            return chalk.green(status);
+        case "halted":
+        case "stopped":
+        case "blocked":
+            return chalk.red(status);
+        default:
+            return status;
+    }
+}
+export function formatCBState(state) {
+    switch (state) {
+        case "CLOSED":
+            return chalk.green(state);
+        case "HALF_OPEN":
+            return chalk.yellow(state);
+        case "OPEN":
+            return chalk.red(state);
+        default:
+            return state;
+    }
+}
+function formatTime(date) {
+    const h = String(date.getUTCHours()).padStart(2, "0");
+    const m = String(date.getUTCMinutes()).padStart(2, "0");
+    const s = String(date.getUTCSeconds()).padStart(2, "0");
+    return `${h}:${m}:${s}`;
+}
+function extractTime(timestamp) {
+    const timePart = timestamp.split(" ")[1];
+    return timePart ?? formatTime(new Date(timestamp));
+}
+export function box(title, lines, cols) {
+    const innerWidth = cols - 2;
+    const titleStr = title ? `\u2500 ${title} ` : "";
+    const topBorder = BOX_CHARS.topLeft +
+        titleStr +
+        BOX_CHARS.horizontal.repeat(Math.max(0, innerWidth - titleStr.length)) +
+        BOX_CHARS.topRight;
+    const bottomBorder = BOX_CHARS.bottomLeft + BOX_CHARS.horizontal.repeat(innerWidth) + BOX_CHARS.bottomRight;
+    const contentLines = lines.map((line) => BOX_CHARS.vertical + " " + padRight(line, innerWidth - 1) + BOX_CHARS.vertical);
+    return [topBorder, ...contentLines, bottomBorder].join("\n");
+}
+export function renderHeader(cols) {
+    const innerWidth = cols - 2;
+    const title = "RALPH MONITOR";
+    const padding = Math.max(0, Math.floor((innerWidth - title.length) / 2));
+    const centeredTitle = " ".repeat(padding) + title + " ".repeat(innerWidth - padding - title.length);
+    const topBorder = BOX_CHARS.headerLeft + BOX_CHARS.headerHoriz.repeat(innerWidth) + BOX_CHARS.headerRight;
+    const titleLine = BOX_CHARS.headerVert + chalk.bold(centeredTitle) + BOX_CHARS.headerVert;
+    const bottomBorder = BOX_CHARS.headerBottom + BOX_CHARS.headerHoriz.repeat(innerWidth) + BOX_CHARS.headerBottomRight;
+    return [topBorder, titleLine, bottomBorder].join("\n");
+}
+export function renderLoopPanel(loop, execution, session, cols) {
+    if (loop === null) {
+        return box("Loop Status", ["Status: waiting for data"], cols);
+    }
+    const apiPercent = loop.maxCallsPerHour > 0
+        ? Math.round((loop.callsMadeThisHour / loop.maxCallsPerHour) * 100)
+        : 0;
+    const loopStr = `Loop: #${String(loop.loopCount)}`;
+    const statusStr = `Status: ${formatStatus(loop.status)}`;
+    const apiStr = `API: ${String(loop.callsMadeThisHour)}/${String(loop.maxCallsPerHour)} (${String(apiPercent)}%)`;
+    const line1 = `${padRight(loopStr, 17)}${padRight(statusStr, 21)}${apiStr}`;
+    const actionLabel = execution !== null ? execution.status : loop.lastAction;
+    const actionStr = `Action: ${actionLabel}`;
+    const sessionStr = session !== null ? `Session: ${formatSessionAge(session.createdAt)}` : "";
+    const innerWidth = cols - 4;
+    const sessionPad = Math.max(0, innerWidth - actionStr.length - sessionStr.length);
+    const line2 = `${actionStr}${" ".repeat(sessionPad)}${sessionStr}`;
+    return box("Loop Status", [line1, line2], cols);
+}
+export function renderCircuitBreakerPanel(cb, cols) {
+    const halfCols = Math.floor(cols / 2) - 1;
+    if (cb === null) {
+        return box("Circuit Breaker", ["N/A"], halfCols);
+    }
+    const lines = [
+        `State: ${formatCBState(cb.state)}`,
+        `No-progress: ${String(cb.consecutiveNoProgress)}`,
+        `Opens: ${String(cb.totalOpens)}`,
+    ];
+    if (cb.state === "OPEN" && cb.reason) {
+        lines.push(`Reason: ${cb.reason}`);
+    }
+    return box("Circuit Breaker", lines, halfCols);
+}
+export function renderStoriesPanel(stories, cols) {
+    const halfCols = Math.floor(cols / 2) - 1;
+    if (stories === null) {
+        return box("Stories", ["N/A"], halfCols);
+    }
+    const total = stories.total;
+    const completed = stories.completed;
+    const percent = total > 0 ? Math.round((completed / total) * 100) : 0;
+    const bar = progressBar(completed, total, 20);
+    const lines = [
+        `Progress: ${String(completed)}/${String(total)} (${String(percent)}%)`,
+        `[${bar}]`,
+    ];
+    if (stories.nextStory !== null) {
+        lines.push(`Next: ${stories.nextStory}`);
+    }
+    return box("Stories", lines, halfCols);
+}
+export function renderSideBySide(left, right, cols) {
+    const halfWidth = Math.floor(cols / 2) - 1;
+    const leftLines = left.split("\n");
+    const rightLines = right.split("\n");
+    const maxLines = Math.max(leftLines.length, rightLines.length);
+    const result = [];
+    for (let i = 0; i < maxLines; i++) {
+        const l = leftLines[i] ?? "";
+        const r = rightLines[i] ?? "";
+        result.push(padRight(l, halfWidth) + "  " + r);
+    }
+    return result.join("\n");
+}
+export function renderAnalysisPanel(analysis, cols) {
+    if (analysis === null) {
+        return box("Last Analysis", ["N/A"], cols);
+    }
+    const yesNo = (v) => (v ? "yes" : "no");
+    const line1 = [
+        `Files: ${String(analysis.filesModified)}`,
+        `Confidence: ${String(analysis.confidenceScore)}%`,
+        `Test-only: ${yesNo(analysis.isTestOnly)}`,
+        `Stuck: ${yesNo(analysis.isStuck)}`,
+    ].join("    ");
+    const line2 = [
+        `Exit signal: ${yesNo(analysis.exitSignal)}`,
+        `Permission denials: ${String(analysis.permissionDenialCount)}`,
+    ].join("    ");
+    return box("Last Analysis", [line1, line2], cols);
+}
+export function renderLogsPanel(logs, cols) {
+    if (logs.length === 0) {
+        return box("Recent Activity", [chalk.dim("No activity yet")], cols);
+    }
+    const innerWidth = cols - 4;
+    const lines = logs.map((entry) => {
+        const time = extractTime(entry.timestamp);
+        const level = padRight(entry.level, 7);
+        const prefix = `[${time}] ${level}`;
+        const maxMsg = Math.max(0, innerWidth - prefix.length - 1);
+        const msg = entry.message.length > maxMsg ? entry.message.slice(0, maxMsg) : entry.message;
+        return `${chalk.dim(`[${time}]`)} ${level} ${msg}`;
+    });
+    return box("Recent Activity", lines, cols);
+}
+export function renderFooter(lastUpdated, cols) {
+    const left = chalk.dim("q quit");
+    const right = `Updated: ${formatTime(lastUpdated)}`;
+    const gap = Math.max(1, cols - "q quit".length - right.length);
+    return ` ${left}${" ".repeat(gap - 1)}${chalk.dim(right)}`;
+}
+function hasAnyData(state) {
+    return (state.loop !== null ||
+        state.circuitBreaker !== null ||
+        state.stories !== null ||
+        state.analysis !== null ||
+        state.execution !== null ||
+        state.session !== null ||
+        state.recentLogs.length > 0);
+}
+export function renderDashboard(state, cols) {
+    const width = cols ?? process.stdout.columns ?? 80;
+    if (!hasAnyData(state)) {
+        const lines = [];
+        lines.push(renderHeader(width));
+        lines.push("");
+        lines.push(chalk.dim(padRight("  Waiting for Ralph to start...", width)));
+        lines.push("");
+        lines.push(renderFooter(state.lastUpdated, width));
+        return lines.join("\n");
+    }
+    const sections = [];
+    sections.push(renderHeader(width));
+    sections.push(renderLoopPanel(state.loop, state.execution, state.session, width));
+    const leftPanel = renderCircuitBreakerPanel(state.circuitBreaker, width);
+    const rightPanel = renderStoriesPanel(state.stories, width);
+    sections.push(renderSideBySide(leftPanel, rightPanel, width));
+    sections.push(renderAnalysisPanel(state.analysis, width));
+    sections.push(renderLogsPanel(state.recentLogs, width));
+    sections.push(renderFooter(state.lastUpdated, width));
+    return sections.join("\n");
+}

package/dist/watch/state-reader.d.ts

@@ -0,0 +1,9 @@
+import type { DashboardState, LoopInfo, CircuitBreakerInfo, StoryProgress, AnalysisInfo, ExecutionProgress, SessionInfo, LogEntry } from "./types.js";
+export declare function readDashboardState(projectDir: string): Promise<DashboardState>;
+export declare function readLoopInfo(projectDir: string): Promise<LoopInfo | null>;
+export declare function readCircuitBreakerInfo(projectDir: string): Promise<CircuitBreakerInfo | null>;
+export declare function readStoryProgress(projectDir: string): Promise<StoryProgress | null>;
+export declare function readAnalysisInfo(projectDir: string): Promise<AnalysisInfo | null>;
+export declare function readExecutionProgress(projectDir: string): Promise<ExecutionProgress | null>;
+export declare function readSessionInfo(projectDir: string): Promise<SessionInfo | null>;
+export declare function readRecentLogs(projectDir: string, maxLines?: number): Promise<LogEntry[]>;

package/dist/watch/state-reader.js

@@ -0,0 +1,190 @@
+import { join } from "path";
+import { open, readFile } from "fs/promises";
+import { readJsonFile } from "../utils/json.js";
+import { RALPH_DIR } from "../utils/constants.js";
+import { parseFixPlan } from "../transition/fix-plan.js";
+import { validateCircuitBreakerState, validateRalphSession, normalizeRalphStatus, } from "../utils/validate.js";
+const LOG_LINE_PATTERN = /^\[(\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2})\] \[(\w+)\] (.+)$/;
+const DEFAULT_MAX_LOG_LINES = 8;
+const TAIL_BYTES = 4096;
+export async function readDashboardState(projectDir) {
+    const [loop, circuitBreaker, stories, analysis, execution, session, recentLogs] = await Promise.all([
+        readLoopInfo(projectDir),
+        readCircuitBreakerInfo(projectDir),
+        readStoryProgress(projectDir),
+        readAnalysisInfo(projectDir),
+        readExecutionProgress(projectDir),
+        readSessionInfo(projectDir),
+        readRecentLogs(projectDir),
+    ]);
+    const ralphCompleted = loop !== null && loop.status === "completed";
+    return {
+        loop,
+        circuitBreaker,
+        stories,
+        analysis,
+        execution,
+        session,
+        recentLogs,
+        ralphCompleted,
+        lastUpdated: new Date(),
+    };
+}
+export async function readLoopInfo(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, "status.json"));
+        if (data === null)
+            return null;
+        const normalized = normalizeRalphStatus(data);
+        const lastAction = typeof data.last_action === "string" ? data.last_action : "";
+        const callsMadeThisHour = typeof data.calls_made_this_hour === "number" ? data.calls_made_this_hour : 0;
+        const maxCallsPerHour = typeof data.max_calls_per_hour === "number" ? data.max_calls_per_hour : 0;
+        return {
+            loopCount: normalized.loopCount,
+            status: normalized.status,
+            lastAction,
+            callsMadeThisHour,
+            maxCallsPerHour,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readCircuitBreakerInfo(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, ".circuit_breaker_state"));
+        if (data === null)
+            return null;
+        const validated = validateCircuitBreakerState(data);
+        const totalOpens = typeof data.total_opens === "number" ? data.total_opens : 0;
+        return {
+            state: validated.state,
+            consecutiveNoProgress: validated.consecutive_no_progress,
+            totalOpens,
+            reason: validated.reason,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readStoryProgress(projectDir) {
+    let content;
+    try {
+        content = await readFile(join(projectDir, RALPH_DIR, "@fix_plan.md"), "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const items = parseFixPlan(content);
+    const completed = items.filter((item) => item.completed).length;
+    const total = items.length;
+    const nextItem = items.find((item) => !item.completed);
+    const nextStory = nextItem ? `Story ${nextItem.id}: ${nextItem.title ?? ""}`.trim() : null;
+    return { completed, total, nextStory };
+}
+export async function readAnalysisInfo(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, ".response_analysis"));
+        if (data === null)
+            return null;
+        const analysis = data.analysis;
+        if (typeof analysis !== "object" || analysis === null)
+            return null;
+        const a = analysis;
+        const filesModified = typeof a.files_modified === "number" ? a.files_modified : 0;
+        const confidenceScore = typeof a.confidence_score === "number" ? a.confidence_score : 0;
+        const isTestOnly = typeof a.is_test_only === "boolean" ? a.is_test_only : false;
+        const isStuck = typeof a.is_stuck === "boolean" ? a.is_stuck : false;
+        const exitSignal = typeof a.exit_signal === "boolean" ? a.exit_signal : false;
+        const hasPermissionDenials = typeof a.has_permission_denials === "boolean" ? a.has_permission_denials : false;
+        const permissionDenialCount = typeof a.permission_denial_count === "number" ? a.permission_denial_count : 0;
+        return {
+            filesModified,
+            confidenceScore,
+            isTestOnly,
+            isStuck,
+            exitSignal,
+            hasPermissionDenials,
+            permissionDenialCount,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readExecutionProgress(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, "progress.json"));
+        if (data === null)
+            return null;
+        const status = typeof data.status === "string" ? data.status : "";
+        if (status !== "executing")
+            return null;
+        const elapsedSeconds = typeof data.elapsed_seconds === "number" ? data.elapsed_seconds : 0;
+        return { status, elapsedSeconds };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readSessionInfo(projectDir) {
+    try {
+        const data = await readJsonFile(join(projectDir, RALPH_DIR, ".ralph_session"));
+        if (data === null)
+            return null;
+        const validated = validateRalphSession(data);
+        return {
+            createdAt: validated.created_at,
+            lastUsed: validated.last_used,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function readRecentLogs(projectDir, maxLines = DEFAULT_MAX_LOG_LINES) {
+    const logPath = join(projectDir, RALPH_DIR, "logs", "ralph.log");
+    let content;
+    try {
+        const fh = await open(logPath, "r");
+        try {
+            const stats = await fh.stat();
+            if (stats.size === 0) {
+                return [];
+            }
+            if (stats.size <= TAIL_BYTES) {
+                content = await fh.readFile("utf-8");
+            }
+            else {
+                const position = stats.size - TAIL_BYTES;
+                const buf = Buffer.alloc(TAIL_BYTES);
+                const { bytesRead } = await fh.read(buf, 0, TAIL_BYTES, position);
+                const raw = buf.toString("utf-8", 0, bytesRead);
+                const newlineIdx = raw.indexOf("\n");
+                content = newlineIdx >= 0 ? raw.slice(newlineIdx + 1) : raw;
+            }
+        }
+        finally {
+            await fh.close();
+        }
+    }
+    catch {
+        return [];
+    }
+    const lines = content.split(/\r?\n/).filter((line) => line.length > 0);
+    const tail = lines.slice(-maxLines);
+    const entries = [];
+    for (const line of tail) {
+        const match = LOG_LINE_PATTERN.exec(line);
+        if (match) {
+            entries.push({
+                timestamp: match[1],
+                level: match[2],
+                message: match[3],
+            });
+        }
+    }
+    return entries;
+}