aoaoe 1.3.0 → 2.5.0

package/dist/metrics-export.js

@@ -0,0 +1,58 @@
+// metrics-export.ts — Prometheus-compatible /metrics endpoint for daemon observability.
+// exports fleet health, session counts, cost, reasoning stats as text/plain metrics.
+/**
+ * Format metrics as Prometheus text exposition format.
+ */
+export function formatPrometheusMetrics(m) {
+    const lines = [];
+    const metric = (name, help, type, value) => {
+        lines.push(`# HELP aoaoe_${name} ${help}`);
+        lines.push(`# TYPE aoaoe_${name} ${type}`);
+        lines.push(`aoaoe_${name} ${value}`);
+    };
+    metric("fleet_health", "Fleet health score 0-100", "gauge", m.fleetHealth);
+    metric("sessions_total", "Total number of sessions", "gauge", m.totalSessions);
+    metric("sessions_active", "Number of active sessions", "gauge", m.activeSessions);
+    metric("sessions_error", "Number of sessions in error state", "gauge", m.errorSessions);
+    metric("tasks_total", "Total number of tasks", "gauge", m.totalTasks);
+    metric("tasks_active", "Number of active tasks", "gauge", m.activeTasks);
+    metric("tasks_completed_total", "Total completed tasks", "counter", m.completedTasks);
+    metric("tasks_failed_total", "Total failed tasks", "counter", m.failedTasks);
+    metric("cost_usd_total", "Total cost in USD", "counter", m.totalCostUsd);
+    metric("reasoner_calls_total", "Total reasoning calls made", "counter", m.reasonerCallsTotal);
+    metric("reasoner_cost_usd_total", "Total reasoner cost in USD", "counter", m.reasonerCostTotal);
+    metric("cache_hits_total", "Observation cache hits", "counter", m.cacheHits);
+    metric("cache_misses_total", "Observation cache misses", "counter", m.cacheMisses);
+    metric("alerts_fired_total", "Total alerts fired", "counter", m.alertsFired);
+    metric("nudges_sent_total", "Total nudges sent", "counter", m.nudgesSent);
+    metric("nudges_effective_total", "Nudges that led to progress", "counter", m.nudgesEffective);
+    metric("poll_interval_ms", "Current adaptive poll interval", "gauge", m.pollIntervalMs);
+    metric("uptime_seconds", "Daemon uptime in seconds", "gauge", Math.round(m.uptimeMs / 1000));
+    return lines.join("\n") + "\n";
+}
+/**
+ * Build a metrics snapshot from daemon state.
+ */
+export function buildMetricsSnapshot(state) {
+    return {
+        fleetHealth: state.fleetHealth ?? 0,
+        totalSessions: state.totalSessions ?? 0,
+        activeSessions: state.activeSessions ?? 0,
+        errorSessions: state.errorSessions ?? 0,
+        totalTasks: state.totalTasks ?? 0,
+        activeTasks: state.activeTasks ?? 0,
+        completedTasks: state.completedTasks ?? 0,
+        failedTasks: state.failedTasks ?? 0,
+        totalCostUsd: state.totalCostUsd ?? 0,
+        reasonerCallsTotal: state.reasonerCallsTotal ?? 0,
+        reasonerCostTotal: state.reasonerCostTotal ?? 0,
+        cacheHits: state.cacheHits ?? 0,
+        cacheMisses: state.cacheMisses ?? 0,
+        alertsFired: state.alertsFired ?? 0,
+        nudgesSent: state.nudgesSent ?? 0,
+        nudgesEffective: state.nudgesEffective ?? 0,
+        pollIntervalMs: state.pollIntervalMs ?? 10_000,
+        uptimeMs: state.uptimeMs ?? 0,
+    };
+}
+//# sourceMappingURL=metrics-export.js.map

package/dist/multi-reasoner.d.ts

@@ -0,0 +1,36 @@
+import type { Observation, ReasonerResult } from "./types.js";
+export type ReasonerBackend = "opencode" | "claude-code" | "gemini" | "custom";
+export interface ReasonerAssignment {
+    sessionTitle: string;
+    backend: ReasonerBackend;
+    reason: string;
+}
+export interface MultiReasonerConfig {
+    defaultBackend: ReasonerBackend;
+    sessionOverrides: Record<string, ReasonerBackend>;
+    templateMappings: Record<string, ReasonerBackend>;
+    difficultyThreshold: number;
+    premiumBackend: ReasonerBackend;
+    economyBackend: ReasonerBackend;
+}
+/**
+ * Determine which reasoner backend to use for each session.
+ */
+export declare function assignReasonerBackends(sessions: Array<{
+    title: string;
+    template?: string;
+    difficultyScore?: number;
+}>, config?: Partial<MultiReasonerConfig>): ReasonerAssignment[];
+/**
+ * Split an observation into per-backend groups for routing.
+ */
+export declare function routeObservation(observation: Observation, assignments: ReasonerAssignment[]): Map<ReasonerBackend, Observation>;
+/**
+ * Merge results from multiple reasoner backends into a single result.
+ */
+export declare function mergeReasonerResults(results: ReasonerResult[]): ReasonerResult;
+/**
+ * Format assignments for TUI display.
+ */
+export declare function formatAssignments(assignments: ReasonerAssignment[]): string[];
+//# sourceMappingURL=multi-reasoner.d.ts.map

package/dist/multi-reasoner.js

@@ -0,0 +1,87 @@
+// multi-reasoner.ts — assign different LLM backends per session.
+// routes observations to the appropriate reasoner based on session config,
+// template, or difficulty. supports reasoner pools with load balancing.
+const DEFAULT_CONFIG = {
+    defaultBackend: "opencode",
+    sessionOverrides: {},
+    templateMappings: {},
+    difficultyThreshold: 7,
+    premiumBackend: "opencode",
+    economyBackend: "claude-code",
+};
+/**
+ * Determine which reasoner backend to use for each session.
+ */
+export function assignReasonerBackends(sessions, config = {}) {
+    const c = { ...DEFAULT_CONFIG, ...config };
+    return sessions.map((s) => {
+        // explicit override wins
+        if (c.sessionOverrides[s.title]) {
+            return { sessionTitle: s.title, backend: c.sessionOverrides[s.title], reason: "explicit override" };
+        }
+        // template mapping
+        if (s.template && c.templateMappings[s.template]) {
+            return { sessionTitle: s.title, backend: c.templateMappings[s.template], reason: `template: ${s.template}` };
+        }
+        // difficulty-based routing
+        if (s.difficultyScore !== undefined) {
+            if (s.difficultyScore >= c.difficultyThreshold) {
+                return { sessionTitle: s.title, backend: c.premiumBackend, reason: `high difficulty (${s.difficultyScore}/10)` };
+            }
+            return { sessionTitle: s.title, backend: c.economyBackend, reason: `low difficulty (${s.difficultyScore}/10)` };
+        }
+        return { sessionTitle: s.title, backend: c.defaultBackend, reason: "default" };
+    });
+}
+/**
+ * Split an observation into per-backend groups for routing.
+ */
+export function routeObservation(observation, assignments) {
+    const assignMap = new Map(assignments.map((a) => [a.sessionTitle, a.backend]));
+    const groups = new Map();
+    for (const snap of observation.sessions) {
+        const backend = assignMap.get(snap.session.title) ?? "opencode";
+        if (!groups.has(backend))
+            groups.set(backend, { sessions: [], changes: [] });
+        groups.get(backend).sessions.push(snap);
+    }
+    for (const change of observation.changes) {
+        const backend = assignMap.get(change.title) ?? "opencode";
+        if (groups.has(backend))
+            groups.get(backend).changes.push(change);
+    }
+    const result = new Map();
+    for (const [backend, data] of groups) {
+        result.set(backend, { timestamp: observation.timestamp, sessions: data.sessions, changes: data.changes });
+    }
+    return result;
+}
+/**
+ * Merge results from multiple reasoner backends into a single result.
+ */
+export function mergeReasonerResults(results) {
+    const allActions = results.flatMap((r) => r.actions);
+    // use lowest confidence across all results
+    const confidences = results.map((r) => r.confidence).filter(Boolean);
+    const confidence = confidences.length > 0
+        ? (confidences.includes("low") ? "low" : confidences.includes("medium") ? "medium" : "high")
+        : undefined;
+    return { actions: allActions, confidence: confidence };
+}
+/**
+ * Format assignments for TUI display.
+ */
+export function formatAssignments(assignments) {
+    if (assignments.length === 0)
+        return ["  (no sessions to assign)"];
+    const lines = [];
+    const backendCounts = new Map();
+    for (const a of assignments) {
+        backendCounts.set(a.backend, (backendCounts.get(a.backend) ?? 0) + 1);
+        lines.push(`  ${a.sessionTitle}: ${a.backend} (${a.reason})`);
+    }
+    const summary = [...backendCounts.entries()].map(([b, c]) => `${b}: ${c}`).join(", ");
+    lines.unshift(`  Multi-reasoner assignments (${summary}):`);
+    return lines;
+}
+//# sourceMappingURL=multi-reasoner.js.map

package/dist/output-archival.d.ts

@@ -0,0 +1,23 @@
+export interface ArchiveResult {
+    sessionTitle: string;
+    filepath: string;
+    originalLines: number;
+    compressedBytes: number;
+    archivedAt: number;
+}
+/**
+ * Archive session output to a gzipped file on disk.
+ */
+export declare function archiveSessionOutput(sessionTitle: string, output: string[], now?: number): ArchiveResult;
+/**
+ * List available archives.
+ */
+export declare function listArchives(): Array<{
+    filename: string;
+    sessionTitle: string;
+}>;
+/**
+ * Format archive list for TUI display.
+ */
+export declare function formatArchiveList(): string[];
+//# sourceMappingURL=output-archival.d.ts.map

package/dist/output-archival.js

@@ -0,0 +1,72 @@
+// output-archival.ts — compress and archive old session outputs to disk.
+// keeps the daemon's memory footprint manageable over long runs by
+// offloading old output to gzipped files.
+import { writeFileSync, mkdirSync, existsSync, readdirSync, unlinkSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { gzipSync } from "node:zlib";
+const ARCHIVE_DIR = join(homedir(), ".aoaoe", "output-archive");
+const MAX_ARCHIVES = 200;
+/**
+ * Archive session output to a gzipped file on disk.
+ */
+export function archiveSessionOutput(sessionTitle, output, now = Date.now()) {
+    mkdirSync(ARCHIVE_DIR, { recursive: true });
+    const safe = sessionTitle.replace(/[^a-zA-Z0-9_-]/g, "_");
+    const timestamp = new Date(now).toISOString().replace(/[:.]/g, "-").slice(0, 19);
+    const filename = `${safe}_${timestamp}.txt.gz`;
+    const filepath = join(ARCHIVE_DIR, filename);
+    const content = output.join("\n");
+    const compressed = gzipSync(Buffer.from(content, "utf-8"));
+    writeFileSync(filepath, compressed);
+    pruneOldArchives();
+    return {
+        sessionTitle,
+        filepath,
+        originalLines: output.length,
+        compressedBytes: compressed.length,
+        archivedAt: now,
+    };
+}
+/**
+ * List available archives.
+ */
+export function listArchives() {
+    if (!existsSync(ARCHIVE_DIR))
+        return [];
+    return readdirSync(ARCHIVE_DIR)
+        .filter((f) => f.endsWith(".txt.gz"))
+        .sort()
+        .reverse()
+        .map((f) => ({
+        filename: f,
+        sessionTitle: f.split("_").slice(0, -2).join("_") || f,
+    }));
+}
+/**
+ * Format archive list for TUI display.
+ */
+export function formatArchiveList() {
+    const archives = listArchives();
+    if (archives.length === 0)
+        return ["  (no archived outputs)"];
+    const lines = [];
+    lines.push(`  Output archives: ${archives.length} files`);
+    for (const a of archives.slice(0, 10)) {
+        lines.push(`    ${a.filename}`);
+    }
+    if (archives.length > 10)
+        lines.push(`    ... and ${archives.length - 10} more`);
+    return lines;
+}
+function pruneOldArchives() {
+    try {
+        const files = readdirSync(ARCHIVE_DIR).filter((f) => f.endsWith(".txt.gz")).sort();
+        while (files.length > MAX_ARCHIVES) {
+            const oldest = files.shift();
+            unlinkSync(join(ARCHIVE_DIR, oldest));
+        }
+    }
+    catch { /* best-effort */ }
+}
+//# sourceMappingURL=output-archival.js.map

package/dist/runbook-executor.d.ts

@@ -0,0 +1,37 @@
+import type { GeneratedRunbook } from "./runbook-generator.js";
+export interface RunbookExecution {
+    runbookTitle: string;
+    steps: ExecutionStep[];
+    status: "pending" | "running" | "completed" | "failed";
+    currentStep: number;
+    startedAt?: number;
+    completedAt?: number;
+}
+export interface ExecutionStep {
+    action: string;
+    detail: string;
+    status: "pending" | "running" | "completed" | "skipped" | "failed";
+    result?: string;
+}
+/**
+ * Create an execution plan from a generated runbook.
+ */
+export declare function createExecution(runbook: GeneratedRunbook): RunbookExecution;
+/**
+ * Advance execution to the next step.
+ * Returns the step to execute, or null if done.
+ */
+export declare function advanceExecution(exec: RunbookExecution, previousStepResult?: string): ExecutionStep | null;
+/**
+ * Skip the current step.
+ */
+export declare function skipStep(exec: RunbookExecution): void;
+/**
+ * Fail the current execution.
+ */
+export declare function failExecution(exec: RunbookExecution, reason: string): void;
+/**
+ * Format execution state for TUI display.
+ */
+export declare function formatExecution(exec: RunbookExecution): string[];
+//# sourceMappingURL=runbook-executor.d.ts.map

package/dist/runbook-executor.js

@@ -0,0 +1,78 @@
+// runbook-executor.ts — auto-execute generated runbook steps.
+// takes a GeneratedRunbook and produces actionable commands for the daemon
+// to execute, with dry-run support and step-by-step confirmation.
+/**
+ * Create an execution plan from a generated runbook.
+ */
+export function createExecution(runbook) {
+    return {
+        runbookTitle: runbook.title,
+        steps: runbook.steps.map((s) => ({
+            action: s.action,
+            detail: s.detail,
+            status: "pending",
+        })),
+        status: "pending",
+        currentStep: 0,
+    };
+}
+/**
+ * Advance execution to the next step.
+ * Returns the step to execute, or null if done.
+ */
+export function advanceExecution(exec, previousStepResult) {
+    if (exec.status === "completed" || exec.status === "failed")
+        return null;
+    // mark previous step as completed
+    if (exec.currentStep > 0 && exec.steps[exec.currentStep - 1].status === "running") {
+        exec.steps[exec.currentStep - 1].status = "completed";
+        exec.steps[exec.currentStep - 1].result = previousStepResult;
+    }
+    if (exec.status === "pending") {
+        exec.status = "running";
+        exec.startedAt = Date.now();
+    }
+    if (exec.currentStep >= exec.steps.length) {
+        exec.status = "completed";
+        exec.completedAt = Date.now();
+        return null;
+    }
+    const step = exec.steps[exec.currentStep];
+    step.status = "running";
+    exec.currentStep++;
+    return step;
+}
+/**
+ * Skip the current step.
+ */
+export function skipStep(exec) {
+    if (exec.currentStep > 0 && exec.steps[exec.currentStep - 1].status === "running") {
+        exec.steps[exec.currentStep - 1].status = "skipped";
+    }
+}
+/**
+ * Fail the current execution.
+ */
+export function failExecution(exec, reason) {
+    exec.status = "failed";
+    if (exec.currentStep > 0) {
+        exec.steps[exec.currentStep - 1].status = "failed";
+        exec.steps[exec.currentStep - 1].result = reason;
+    }
+}
+/**
+ * Format execution state for TUI display.
+ */
+export function formatExecution(exec) {
+    const lines = [];
+    const duration = exec.startedAt ? (exec.completedAt ?? Date.now()) - exec.startedAt : 0;
+    lines.push(`  Runbook: ${exec.runbookTitle} (${exec.status}, ${Math.round(duration / 1000)}s)`);
+    for (let i = 0; i < exec.steps.length; i++) {
+        const s = exec.steps[i];
+        const icon = s.status === "completed" ? "✓" : s.status === "running" ? "▶" : s.status === "failed" ? "✗" : s.status === "skipped" ? "⏭" : "○";
+        const result = s.result ? ` → ${s.result.slice(0, 50)}` : "";
+        lines.push(`  ${icon} ${i + 1}. ${s.action}: ${s.detail}${result}`);
+    }
+    return lines;
+}
+//# sourceMappingURL=runbook-executor.js.map

package/dist/runbook-generator.d.ts

@@ -0,0 +1,21 @@
+export interface RunbookStep {
+    action: string;
+    detail: string;
+    frequency: number;
+}
+export interface GeneratedRunbook {
+    title: string;
+    scenario: string;
+    steps: RunbookStep[];
+    basedOnEvents: number;
+    confidence: "low" | "medium" | "high";
+}
+/**
+ * Analyze audit trail and generate runbooks for common patterns.
+ */
+export declare function generateRunbooks(): GeneratedRunbook[];
+/**
+ * Format generated runbooks for TUI display.
+ */
+export declare function formatGeneratedRunbooks(runbooks: GeneratedRunbook[]): string[];
+//# sourceMappingURL=runbook-generator.d.ts.map

package/dist/runbook-generator.js

@@ -0,0 +1,104 @@
+// runbook-generator.ts — auto-generate operator runbooks from audit trail patterns.
+// analyzes recurring event sequences and produces step-by-step playbooks
+// for common scenarios (stuck sessions, budget overruns, error recovery).
+import { readRecentAuditEntries } from "./audit-trail.js";
+/**
+ * Analyze audit trail and generate runbooks for common patterns.
+ */
+export function generateRunbooks() {
+    const entries = readRecentAuditEntries(5_000);
+    if (entries.length < 10)
+        return [];
+    const runbooks = [];
+    // pattern 1: stuck session recovery
+    const stuckEntries = entries.filter((e) => e.type === "stuck_nudge" || e.type === "session_restart");
+    if (stuckEntries.length >= 3) {
+        const actions = countActions(stuckEntries);
+        runbooks.push({
+            title: "Stuck Session Recovery",
+            scenario: "Session has not made progress for >30 minutes",
+            steps: actions,
+            basedOnEvents: stuckEntries.length,
+            confidence: stuckEntries.length >= 10 ? "high" : stuckEntries.length >= 5 ? "medium" : "low",
+        });
+    }
+    // pattern 2: budget management
+    const budgetEntries = entries.filter((e) => e.type === "budget_pause");
+    if (budgetEntries.length >= 2) {
+        runbooks.push({
+            title: "Budget Overrun Response",
+            scenario: "Session cost exceeds configured budget",
+            steps: [
+                { action: "Review cost attribution", detail: "Use /cost-report to identify top spenders", frequency: budgetEntries.length },
+                { action: "Adjust budget or pause", detail: "Use /budget-predict to estimate remaining runway", frequency: budgetEntries.length },
+                { action: "Check for runaway loops", detail: "Use /drift to verify session is on-task", frequency: Math.ceil(budgetEntries.length * 0.5) },
+            ],
+            basedOnEvents: budgetEntries.length,
+            confidence: budgetEntries.length >= 5 ? "high" : "medium",
+        });
+    }
+    // pattern 3: error recovery
+    const errorEntries = entries.filter((e) => e.type === "session_error");
+    if (errorEntries.length >= 3) {
+        runbooks.push({
+            title: "Session Error Recovery",
+            scenario: "Session enters error state",
+            steps: [
+                { action: "Check session output", detail: "Use /session-replay to review recent activity", frequency: errorEntries.length },
+                { action: "Review recovery playbook", detail: "Use /recovery to see auto-recovery status", frequency: errorEntries.length },
+                { action: "Restart if needed", detail: "Recovery playbook auto-restarts at health <40", frequency: Math.ceil(errorEntries.length * 0.3) },
+            ],
+            basedOnEvents: errorEntries.length,
+            confidence: errorEntries.length >= 10 ? "high" : "medium",
+        });
+    }
+    // pattern 4: goal completion
+    const completionEntries = entries.filter((e) => e.type === "auto_complete" || e.type === "task_completed");
+    if (completionEntries.length >= 3) {
+        runbooks.push({
+            title: "Task Completion Workflow",
+            scenario: "Task auto-detected as complete",
+            steps: [
+                { action: "Verify completion", detail: "Check /goal-progress and /velocity for confirmation", frequency: completionEntries.length },
+                { action: "Review output", detail: "Use /session-replay to verify work quality", frequency: completionEntries.length },
+                { action: "Advance dependencies", detail: "Use /schedule to activate dependent tasks", frequency: Math.ceil(completionEntries.length * 0.5) },
+            ],
+            basedOnEvents: completionEntries.length,
+            confidence: completionEntries.length >= 10 ? "high" : "medium",
+        });
+    }
+    return runbooks;
+}
+/**
+ * Format generated runbooks for TUI display.
+ */
+export function formatGeneratedRunbooks(runbooks) {
+    if (runbooks.length === 0)
+        return ["  (insufficient audit data to generate runbooks — need 10+ events)"];
+    const lines = [];
+    for (const rb of runbooks) {
+        const conf = rb.confidence === "high" ? "●" : rb.confidence === "medium" ? "◐" : "○";
+        lines.push(`  ${conf} ${rb.title} (based on ${rb.basedOnEvents} events)`);
+        lines.push(`    Scenario: ${rb.scenario}`);
+        for (let i = 0; i < rb.steps.length; i++) {
+            lines.push(`    ${i + 1}. ${rb.steps[i].action} — ${rb.steps[i].detail}`);
+        }
+        lines.push("");
+    }
+    return lines;
+}
+function countActions(entries) {
+    const counts = new Map();
+    for (const e of entries) {
+        const key = e.type;
+        const existing = counts.get(key);
+        if (existing)
+            existing.count++;
+        else
+            counts.set(key, { detail: e.detail.slice(0, 80), count: 1 });
+    }
+    return [...counts.entries()].map(([action, { detail, count }]) => ({
+        action, detail, frequency: count,
+    })).sort((a, b) => b.frequency - a.frequency);
+}
+//# sourceMappingURL=runbook-generator.js.map

package/dist/session-checkpoint.d.ts

@@ -0,0 +1,55 @@
+export interface DaemonCheckpoint {
+    version: number;
+    savedAt: number;
+    graduation: Record<string, {
+        mode: string;
+        successes: number;
+        failures: number;
+        rate: number;
+    }>;
+    escalation: Record<string, {
+        level: string;
+        notifyCount: number;
+    }>;
+    velocitySamples: Record<string, Array<{
+        timestamp: number;
+        percent: number;
+    }>>;
+    nudgeRecords: Array<{
+        session: string;
+        sentAt: number;
+        effective: boolean;
+    }>;
+    budgetSamples: Record<string, Array<{
+        timestamp: number;
+        costUsd: number;
+    }>>;
+    cacheStats: {
+        hits: number;
+        misses: number;
+    };
+    slaHistory: number[];
+    pollInterval: number;
+}
+/**
+ * Save daemon state to a checkpoint file.
+ */
+export declare function saveCheckpoint(checkpoint: DaemonCheckpoint): string;
+/**
+ * Load the most recent checkpoint. Returns null if none exists.
+ */
+export declare function loadCheckpoint(): DaemonCheckpoint | null;
+/**
+ * Build a checkpoint from current module states.
+ * This is a generic serialization — callers extract state from each module.
+ */
+export declare function buildCheckpoint(state: Omit<DaemonCheckpoint, "version" | "savedAt">): DaemonCheckpoint;
+/**
+ * Format checkpoint info for TUI display.
+ */
+export declare function formatCheckpointInfo(): string[];
+/**
+ * Check if a checkpoint exists and is recent enough to restore.
+ */
+export declare function shouldRestoreCheckpoint(maxAgeMs?: number): boolean;
+//# sourceMappingURL=session-checkpoint.d.ts.map

package/dist/session-checkpoint.js

@@ -0,0 +1,69 @@
+// session-checkpoint.ts — save + resume session state across daemon restarts.
+// serializes all transient module state (graduation, escalation, velocity,
+// nudge tracker, etc.) to disk so the daemon can pick up where it left off.
+import { writeFileSync, readFileSync, existsSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+const CHECKPOINT_DIR = join(homedir(), ".aoaoe", "checkpoints");
+const CHECKPOINT_FILE = join(CHECKPOINT_DIR, "daemon-state.json");
+/**
+ * Save daemon state to a checkpoint file.
+ */
+export function saveCheckpoint(checkpoint) {
+    mkdirSync(CHECKPOINT_DIR, { recursive: true });
+    checkpoint.savedAt = Date.now();
+    checkpoint.version = 1;
+    writeFileSync(CHECKPOINT_FILE, JSON.stringify(checkpoint, null, 2) + "\n");
+    return CHECKPOINT_FILE;
+}
+/**
+ * Load the most recent checkpoint. Returns null if none exists.
+ */
+export function loadCheckpoint() {
+    if (!existsSync(CHECKPOINT_FILE))
+        return null;
+    try {
+        const data = JSON.parse(readFileSync(CHECKPOINT_FILE, "utf-8"));
+        if (data.version !== 1)
+            return null; // incompatible version
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Build a checkpoint from current module states.
+ * This is a generic serialization — callers extract state from each module.
+ */
+export function buildCheckpoint(state) {
+    return { version: 1, savedAt: Date.now(), ...state };
+}
+/**
+ * Format checkpoint info for TUI display.
+ */
+export function formatCheckpointInfo() {
+    const cp = loadCheckpoint();
+    if (!cp)
+        return ["  (no checkpoint found)"];
+    const age = Math.round((Date.now() - cp.savedAt) / 60_000);
+    const lines = [];
+    lines.push(`  Checkpoint: saved ${age}min ago`);
+    lines.push(`  Graduation: ${Object.keys(cp.graduation).length} sessions`);
+    lines.push(`  Escalation: ${Object.keys(cp.escalation).length} active`);
+    lines.push(`  Velocity: ${Object.keys(cp.velocitySamples).length} tracked`);
+    lines.push(`  Nudges: ${cp.nudgeRecords.length} records`);
+    lines.push(`  Cache: ${cp.cacheStats.hits} hits / ${cp.cacheStats.misses} misses`);
+    lines.push(`  SLA history: ${cp.slaHistory.length} ticks`);
+    return lines;
+}
+/**
+ * Check if a checkpoint exists and is recent enough to restore.
+ */
+export function shouldRestoreCheckpoint(maxAgeMs = 30 * 60_000) {
+    const cp = loadCheckpoint();
+    if (!cp)
+        return false;
+    return (Date.now() - cp.savedAt) <= maxAgeMs;
+}
+//# sourceMappingURL=session-checkpoint.js.map

package/dist/session-tail.d.ts

@@ -0,0 +1,24 @@
+export interface TailOptions {
+    sessionTitle: string;
+    lineCount: number;
+    highlightPattern?: string;
+    stripAnsi: boolean;
+}
+/**
+ * Extract the last N lines from session output, optionally highlighting matches.
+ */
+export declare function tailSession(output: string[], options: Partial<TailOptions> & {
+    sessionTitle: string;
+}): string[];
+/**
+ * Format tail output for TUI display.
+ */
+export declare function formatTail(sessionTitle: string, lines: string[], total: number): string[];
+/**
+ * Parse tail command arguments.
+ * Format: /tail <session> [count] [pattern]
+ */
+export declare function parseTailArgs(args: string): Partial<TailOptions> & {
+    sessionTitle: string;
+};
+//# sourceMappingURL=session-tail.d.ts.map