@ginkoai/cli 2.5.1 → 2.5.2

package/dist/lib/session-health.js

@@ -0,0 +1,252 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-03-15
+ * @tags: [session-health, context-pressure, degradation, epic-025]
+ * @related: [context-metrics.ts, output-formatter.ts, health-checker.ts]
+ * @priority: high
+ * @complexity: low
+ * @dependencies: [fs-extra]
+ */
+/**
+ * Session Health Tier Calculation (EPIC-025 Sprint 4)
+ *
+ * Calculates a health tier from session metrics (message count, duration)
+ * to surface context degradation risk to the human partner.
+ *
+ * The AI partner under cognitive load is the worst judge of its own
+ * degradation — EPIC-024 proved this at ~40 messages / ~200K tokens.
+ * The human needs the signal.
+ *
+ * Thresholds calibrated against EPIC-023/024 session data:
+ * - EPIC-024: First deployment failure at ~35 messages, serial bug fixing at ~45
+ * - EPIC-023: Context score drop at ~30 messages, CLI interop bugs at ~40
+ *
+ * Compression events: Claude Code does NOT emit hook events for /compact.
+ * Message count + duration remain the primary degradation signals.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+// =============================================================================
+// Defaults
+// =============================================================================
+/**
+ * Default thresholds calibrated against EPIC-023/024 session data.
+ *
+ * EPIC-024 (262K token session):
+ *   - Deployment failures began at ~35 messages
+ *   - Serial bug fixing pattern at ~45 messages
+ *   - Subagent collision at ~50 messages
+ *
+ * EPIC-023 (multi-session analysis):
+ *   - Context score degradation at ~30 messages
+ *   - CLI interop bugs surfaced at ~40 messages
+ *   - E2E walkthrough late verification at ~45 messages
+ */
+export const DEFAULT_THRESHOLDS = {
+    steadyMessages: 15,
+    verifyMessages: 35,
+    handoffMessages: 50,
+    steadyDurationMin: 60,
+    verifyDurationMin: 180,
+    handoffDurationMin: 300,
+};
+// =============================================================================
+// Tier Calculation
+// =============================================================================
+/**
+ * Calculate health tier from message count and session duration.
+ *
+ * Uses the higher of message-based or duration-based tier
+ * (whichever indicates more pressure).
+ */
+export function calculateHealthTier(messageCount, durationMinutes, thresholds = DEFAULT_THRESHOLDS) {
+    // Message-based tier
+    let messageTier = 'fresh';
+    if (messageCount >= thresholds.handoffMessages) {
+        messageTier = 'handoff-recommended';
+    }
+    else if (messageCount >= thresholds.verifyMessages) {
+        messageTier = 'verify-deploys';
+    }
+    else if (messageCount >= thresholds.steadyMessages) {
+        messageTier = 'steady';
+    }
+    // Duration-based tier
+    let durationTier = 'fresh';
+    if (durationMinutes >= thresholds.handoffDurationMin) {
+        durationTier = 'handoff-recommended';
+    }
+    else if (durationMinutes >= thresholds.verifyDurationMin) {
+        durationTier = 'verify-deploys';
+    }
+    else if (durationMinutes >= thresholds.steadyDurationMin) {
+        durationTier = 'steady';
+    }
+    // Use the higher (more concerning) tier
+    const tierOrder = ['fresh', 'steady', 'verify-deploys', 'handoff-recommended'];
+    const messageIdx = tierOrder.indexOf(messageTier);
+    const durationIdx = tierOrder.indexOf(durationTier);
+    const tier = tierOrder[Math.max(messageIdx, durationIdx)];
+    return {
+        tier,
+        icon: getTierIcon(tier),
+        label: getTierLabel(tier),
+        messageCount,
+        durationMinutes,
+    };
+}
+function getTierIcon(tier) {
+    switch (tier) {
+        case 'fresh': return '✅';
+        case 'steady': return '◐';
+        case 'verify-deploys': return '⚠️';
+        case 'handoff-recommended': return '🔄';
+    }
+}
+function getTierLabel(tier) {
+    switch (tier) {
+        case 'fresh': return 'fresh';
+        case 'steady': return 'steady';
+        case 'verify-deploys': return 'verify deploys';
+        case 'handoff-recommended': return 'handoff recommended';
+    }
+}
+// =============================================================================
+// Session Metrics Extraction
+// =============================================================================
+/**
+ * Count messages in the current session from events JSONL.
+ */
+export async function getSessionMessageCount(projectRoot) {
+    try {
+        const root = projectRoot || getProjectRoot();
+        const sessionsDir = path.join(root, '.ginko', 'sessions');
+        if (!await fs.pathExists(sessionsDir))
+            return 0;
+        const dirs = await fs.readdir(sessionsDir);
+        for (const dir of dirs) {
+            const eventsFile = path.join(sessionsDir, dir, 'current-events.jsonl');
+            if (await fs.pathExists(eventsFile)) {
+                const content = await fs.readFile(eventsFile, 'utf-8');
+                const lines = content.split('\n').filter(l => l.trim());
+                // Count message-type events
+                let count = 0;
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.type === 'message' || event.type === 'tool_call' ||
+                            event.type === 'context_score' || event.type === 'task_complete' ||
+                            event.type === 'task_start') {
+                            count++;
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+                return count || lines.length;
+            }
+        }
+    }
+    catch {
+        // Metric extraction failure returns 0
+    }
+    return 0;
+}
+/**
+ * Get session duration in minutes from session start timestamp.
+ */
+export async function getSessionDurationMinutes(projectRoot) {
+    try {
+        const root = projectRoot || getProjectRoot();
+        const sessionsDir = path.join(root, '.ginko', 'sessions');
+        if (!await fs.pathExists(sessionsDir))
+            return 0;
+        const dirs = await fs.readdir(sessionsDir);
+        for (const dir of dirs) {
+            const eventsFile = path.join(sessionsDir, dir, 'current-events.jsonl');
+            if (await fs.pathExists(eventsFile)) {
+                const content = await fs.readFile(eventsFile, 'utf-8');
+                const lines = content.split('\n').filter(l => l.trim());
+                if (lines.length === 0)
+                    return 0;
+                // Find earliest timestamp
+                let earliest = null;
+                for (const line of lines) {
+                    try {
+                        const event = JSON.parse(line);
+                        if (event.timestamp) {
+                            const ts = new Date(event.timestamp).getTime();
+                            if (!earliest || ts < earliest)
+                                earliest = ts;
+                        }
+                    }
+                    catch {
+                        // Skip malformed lines
+                    }
+                }
+                if (earliest) {
+                    return Math.round((Date.now() - earliest) / 60000);
+                }
+            }
+        }
+    }
+    catch {
+        // Duration extraction failure returns 0
+    }
+    return 0;
+}
+/**
+ * Load custom thresholds from .ginko/config.json if configured.
+ */
+export async function loadThresholds(projectRoot) {
+    try {
+        const root = projectRoot || getProjectRoot();
+        const configFile = path.join(root, '.ginko', 'config.json');
+        if (await fs.pathExists(configFile)) {
+            const config = await fs.readJson(configFile);
+            if (config.healthThresholds) {
+                return { ...DEFAULT_THRESHOLDS, ...config.healthThresholds };
+            }
+        }
+    }
+    catch {
+        // Config load failure uses defaults
+    }
+    return DEFAULT_THRESHOLDS;
+}
+// =============================================================================
+// Convenience
+// =============================================================================
+/**
+ * Get current session health tier (all-in-one).
+ */
+export async function getCurrentHealthTier(projectRoot) {
+    const [messageCount, durationMinutes, thresholds] = await Promise.all([
+        getSessionMessageCount(projectRoot),
+        getSessionDurationMinutes(projectRoot),
+        loadThresholds(projectRoot),
+    ]);
+    return calculateHealthTier(messageCount, durationMinutes, thresholds);
+}
+/**
+ * Format health tier for status line display.
+ * Compact format: "12 msgs | ✅ fresh"
+ */
+export function formatHealthForStatusLine(info) {
+    return `${info.messageCount} msgs | ${info.icon} ${info.label}`;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+function getProjectRoot() {
+    try {
+        const { execSync } = require('child_process');
+        return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+//# sourceMappingURL=session-health.js.map

package/dist/lib/session-health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-health.js","sourceRoot":"","sources":["../../src/lib/session-health.ts"],"names":[],"mappings":"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"}

package/dist/lib/sprint-state.d.ts

@@ -0,0 +1,82 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-03-15
+ * @tags: [sprint-state, cache, materialization, epic-025]
+ * @related: [task-parser.ts, sprint-loader.ts, ../commands/task/status.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+export interface SprintStateTask {
+    title: string;
+    status: string;
+    knownIssues?: string[];
+    blockers?: string[];
+    modifiedFiles?: string[];
+}
+export interface SprintStateProgress {
+    complete: number;
+    total: number;
+    percentage: number;
+}
+export interface SprintState {
+    sprint: string;
+    epicId: string;
+    epicTitle: string;
+    sprintTitle: string;
+    progress: SprintStateProgress;
+    tasks: Record<string, SprintStateTask>;
+    knownIssues: string[];
+    blockers: string[];
+    lastDeployed: string | null;
+    lastUpdated: string;
+    lastUpdatedBy: string | null;
+    stale: boolean;
+}
+/**
+ * Materialize sprint state from graph to local cache.
+ *
+ * Uses getActiveSprint API to fetch current sprint data,
+ * then writes structured JSON to .ginko/sprint-state.json.
+ *
+ * @param projectRoot - Optional project root override
+ * @returns The materialized SprintState, or null if no active sprint
+ */
+export declare function materializeSprintState(projectRoot?: string): Promise<SprintState | null>;
+/**
+ * Read sprint state from local cache.
+ *
+ * @param projectRoot - Optional project root override
+ * @returns SprintState or null if cache doesn't exist
+ */
+export declare function readSprintState(projectRoot?: string): Promise<SprintState | null>;
+/**
+ * Check if cache is stale (>1 hour old).
+ */
+export declare function isCacheStale(state: SprintState, thresholdMs?: number): boolean;
+/**
+ * Push checkpoint data to a task node in the graph.
+ *
+ * @param taskId - Task ID
+ * @param checkpoint - Checkpoint data (knownIssues, blockers, modifiedFiles)
+ */
+export declare function pushCheckpointToGraph(taskId: string, checkpoint: {
+    knownIssues?: string[];
+    blockers?: string[];
+    modifiedFiles?: string[];
+    lastDeployed?: string;
+}): Promise<void>;
+/**
+ * Get modified files from git since last task complete.
+ */
+export declare function getModifiedFiles(): string[];
+/**
+ * Format sprint state for CLI display.
+ */
+export declare function formatSprintState(state: SprintState): string;
+/**
+ * Format a compact sprint checkpoint for ginko start readiness message.
+ */
+export declare function formatCheckpointSummary(state: SprintState): string;
+//# sourceMappingURL=sprint-state.d.ts.map

package/dist/lib/sprint-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprint-state.d.ts","sourceRoot":"","sources":["../../src/lib/sprint-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAsBH,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,mBAAmB,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACvC,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,KAAK,EAAE,OAAO,CAAC;CAChB;AAuBD;;;;;;;;GAQG;AACH,wBAAsB,sBAAsB,CAC1C,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAqG7B;AAwBD;;;;;GAKG;AACH,wBAAsB,eAAe,CACnC,WAAW,CAAC,EAAE,MAAM,GACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAQ7B;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,WAAW,GAAE,MAAgB,GAAG,OAAO,CAIvF;AAMD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,UAAU,EAAE;IACV,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB,GACA,OAAO,CAAC,IAAI,CAAC,CAmCf;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,MAAM,EAAE,CAa3C;AAMD;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CAqD5D;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,WAAW,GAAG,MAAM,CA0BlE"}

package/dist/lib/sprint-state.js

@@ -0,0 +1,338 @@
+/**
+ * @fileType: utility
+ * @status: current
+ * @updated: 2026-03-15
+ * @tags: [sprint-state, cache, materialization, epic-025]
+ * @related: [task-parser.ts, sprint-loader.ts, ../commands/task/status.ts]
+ * @priority: high
+ * @complexity: medium
+ * @dependencies: [fs-extra, path]
+ */
+/**
+ * Sprint State Materialization (EPIC-025 Sprint 2)
+ *
+ * Materializes graph state as `.ginko/sprint-state.json` — a read-only
+ * local cache the AI partner can access with zero friction.
+ *
+ * Write path: AI partner → `ginko task complete` → CLI → graph → local cache
+ * Read path: AI partner → `Read .ginko/sprint-state.json` (one tool call)
+ *
+ * The AI partner never writes to the cache directly. The CLI is the only writer.
+ */
+import fs from 'fs-extra';
+import path from 'path';
+import { execSync } from 'child_process';
+// =============================================================================
+// Helpers
+// =============================================================================
+function getProjectRoot() {
+    try {
+        return execSync('git rev-parse --show-toplevel', { encoding: 'utf-8' }).trim();
+    }
+    catch {
+        return process.cwd();
+    }
+}
+function getCachePath(projectRoot) {
+    const root = projectRoot || getProjectRoot();
+    return path.join(root, '.ginko', 'sprint-state.json');
+}
+// =============================================================================
+// Materialization
+// =============================================================================
+/**
+ * Materialize sprint state from graph to local cache.
+ *
+ * Uses getActiveSprint API to fetch current sprint data,
+ * then writes structured JSON to .ginko/sprint-state.json.
+ *
+ * @param projectRoot - Optional project root override
+ * @returns The materialized SprintState, or null if no active sprint
+ */
+export async function materializeSprintState(projectRoot) {
+    const root = projectRoot || getProjectRoot();
+    const cachePath = getCachePath(root);
+    try {
+        // Dynamic import to avoid circular dependencies
+        const { GraphApiClient } = await import('../commands/graph/api-client.js');
+        const { getGraphId } = await import('../commands/graph/config.js');
+        const graphId = process.env.GINKO_GRAPH_ID || await getGraphId();
+        if (!graphId)
+            return null;
+        const client = new GraphApiClient();
+        const activeSprint = await client.getActiveSprint(graphId);
+        if (!activeSprint?.sprint?.id)
+            return null;
+        // Build task map
+        const tasks = {};
+        const allKnownIssues = [];
+        const allBlockers = [];
+        let completedCount = 0;
+        for (const task of activeSprint.tasks || []) {
+            const taskEntry = {
+                title: task.title || 'Untitled',
+                status: task.status || 'not_started',
+            };
+            // Try to get extended properties (knownIssues, blockers) from graph node
+            try {
+                const nodeResponse = await client.request('GET', `/api/v1/graph/nodes/${encodeURIComponent(task.id)}?graphId=${encodeURIComponent(graphId)}`);
+                const props = nodeResponse.node?.properties;
+                if (props) {
+                    if (props.knownIssues) {
+                        const issues = Array.isArray(props.knownIssues)
+                            ? props.knownIssues
+                            : typeof props.knownIssues === 'string'
+                                ? JSON.parse(props.knownIssues)
+                                : [];
+                        taskEntry.knownIssues = issues;
+                        allKnownIssues.push(...issues);
+                    }
+                    if (props.blockers) {
+                        const blockers = Array.isArray(props.blockers)
+                            ? props.blockers
+                            : typeof props.blockers === 'string'
+                                ? JSON.parse(props.blockers)
+                                : [];
+                        taskEntry.blockers = blockers;
+                        allBlockers.push(...blockers);
+                    }
+                    if (props.modifiedFiles) {
+                        taskEntry.modifiedFiles = Array.isArray(props.modifiedFiles)
+                            ? props.modifiedFiles
+                            : typeof props.modifiedFiles === 'string'
+                                ? JSON.parse(props.modifiedFiles)
+                                : [];
+                    }
+                }
+            }
+            catch {
+                // Individual task property fetch failures are non-fatal
+            }
+            if (task.status === 'complete')
+                completedCount++;
+            tasks[task.id] = taskEntry;
+        }
+        const totalTasks = activeSprint.tasks?.length || 0;
+        const state = {
+            sprint: activeSprint.sprint.id,
+            epicId: activeSprint.sprint.id.split('_')[0] || 'unknown',
+            epicTitle: '',
+            sprintTitle: activeSprint.sprint.name || activeSprint.sprint.id,
+            progress: {
+                complete: completedCount,
+                total: totalTasks,
+                percentage: totalTasks > 0 ? Math.round((completedCount / totalTasks) * 100) : 0,
+            },
+            tasks,
+            knownIssues: [...new Set(allKnownIssues)],
+            blockers: [...new Set(allBlockers)],
+            lastDeployed: null,
+            lastUpdated: new Date().toISOString(),
+            lastUpdatedBy: null,
+            stale: false,
+        };
+        // Write cache
+        await fs.ensureDir(path.dirname(cachePath));
+        await fs.writeJson(cachePath, state, { spaces: 2 });
+        return state;
+    }
+    catch {
+        // Graph unavailable — try to keep existing cache, mark as stale
+        return markCacheStale(cachePath);
+    }
+}
+/**
+ * Mark existing cache as stale (graph was unavailable).
+ * Never deletes the cache — stale data is better than no data.
+ */
+async function markCacheStale(cachePath) {
+    try {
+        if (await fs.pathExists(cachePath)) {
+            const existing = await fs.readJson(cachePath);
+            existing.stale = true;
+            await fs.writeJson(cachePath, existing, { spaces: 2 });
+            return existing;
+        }
+    }
+    catch {
+        // Can't even read the cache — nothing to do
+    }
+    return null;
+}
+// =============================================================================
+// Cache Reading
+// =============================================================================
+/**
+ * Read sprint state from local cache.
+ *
+ * @param projectRoot - Optional project root override
+ * @returns SprintState or null if cache doesn't exist
+ */
+export async function readSprintState(projectRoot) {
+    const cachePath = getCachePath(projectRoot);
+    try {
+        if (!await fs.pathExists(cachePath))
+            return null;
+        return await fs.readJson(cachePath);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Check if cache is stale (>1 hour old).
+ */
+export function isCacheStale(state, thresholdMs = 3600000) {
+    if (state.stale)
+        return true;
+    const age = Date.now() - new Date(state.lastUpdated).getTime();
+    return age > thresholdMs;
+}
+// =============================================================================
+// Checkpoint Updates
+// =============================================================================
+/**
+ * Push checkpoint data to a task node in the graph.
+ *
+ * @param taskId - Task ID
+ * @param checkpoint - Checkpoint data (knownIssues, blockers, modifiedFiles)
+ */
+export async function pushCheckpointToGraph(taskId, checkpoint) {
+    try {
+        const { GraphApiClient } = await import('../commands/graph/api-client.js');
+        const { getGraphId } = await import('../commands/graph/config.js');
+        const graphId = process.env.GINKO_GRAPH_ID || await getGraphId();
+        if (!graphId)
+            return;
+        const client = new GraphApiClient();
+        // Update task node with checkpoint properties
+        const props = {};
+        if (checkpoint.knownIssues?.length) {
+            props.knownIssues = JSON.stringify(checkpoint.knownIssues);
+        }
+        if (checkpoint.blockers?.length) {
+            props.blockers = JSON.stringify(checkpoint.blockers);
+        }
+        if (checkpoint.modifiedFiles?.length) {
+            props.modifiedFiles = JSON.stringify(checkpoint.modifiedFiles);
+        }
+        if (checkpoint.lastDeployed) {
+            props.lastDeployed = checkpoint.lastDeployed;
+        }
+        if (Object.keys(props).length > 0) {
+            await client.request('PATCH', `/api/v1/graph/nodes/${encodeURIComponent(taskId)}?graphId=${encodeURIComponent(graphId)}`, props);
+        }
+    }
+    catch {
+        // Checkpoint push failure is non-fatal — log but don't block
+    }
+}
+/**
+ * Get modified files from git since last task complete.
+ */
+export function getModifiedFiles() {
+    try {
+        const diff = execSync('git diff --name-only HEAD', { encoding: 'utf-8' }).trim();
+        const untracked = execSync('git ls-files --others --exclude-standard', { encoding: 'utf-8' }).trim();
+        const files = new Set();
+        if (diff)
+            diff.split('\n').forEach(f => files.add(f));
+        if (untracked)
+            untracked.split('\n').forEach(f => files.add(f));
+        return Array.from(files).filter(f => f.length > 0).sort();
+    }
+    catch {
+        return [];
+    }
+}
+// =============================================================================
+// Formatting
+// =============================================================================
+/**
+ * Format sprint state for CLI display.
+ */
+export function formatSprintState(state) {
+    const lines = [];
+    lines.push(`Sprint: ${state.sprint} — ${state.sprintTitle}`);
+    lines.push(`Progress: ${state.progress.percentage}% (${state.progress.complete}/${state.progress.total} tasks complete)`);
+    lines.push('');
+    // Tasks
+    lines.push('Tasks:');
+    for (const [id, task] of Object.entries(state.tasks)) {
+        const shortId = id.split('_').pop() || id;
+        let icon;
+        switch (task.status) {
+            case 'complete':
+                icon = '✅';
+                break;
+            case 'in_progress':
+                icon = '🔄';
+                break;
+            case 'blocked':
+                icon = '⛔';
+                break;
+            default:
+                icon = '⬜';
+                break;
+        }
+        lines.push(`  ${icon} ${shortId}: ${task.title}`);
+    }
+    // Known Issues
+    if (state.knownIssues.length > 0) {
+        lines.push('');
+        lines.push('Known Issues:');
+        for (const issue of state.knownIssues) {
+            lines.push(`  - ${issue}`);
+        }
+    }
+    // Blockers
+    if (state.blockers.length > 0) {
+        lines.push('');
+        lines.push('Blockers:');
+        for (const blocker of state.blockers) {
+            lines.push(`  - ${blocker}`);
+        }
+    }
+    else {
+        lines.push('');
+        lines.push('Blockers: none');
+    }
+    if (state.lastDeployed) {
+        lines.push(`Last deployed: ${state.lastDeployed}`);
+    }
+    lines.push(`Last updated: ${state.lastUpdated}${state.lastUpdatedBy ? ` (after ${state.lastUpdatedBy})` : ''}`);
+    if (state.stale) {
+        lines.push('⚠ Cache may be stale — run `ginko pull` to refresh');
+    }
+    return lines.join('\n');
+}
+/**
+ * Format a compact sprint checkpoint for ginko start readiness message.
+ */
+export function formatCheckpointSummary(state) {
+    const lines = [];
+    lines.push(`Sprint: ${state.sprint} — ${state.sprintTitle} (${state.progress.percentage}%)`);
+    // Find last completed and next task
+    let lastCompleted = null;
+    let nextTask = null;
+    const taskEntries = Object.entries(state.tasks);
+    for (const [id, task] of taskEntries) {
+        if (task.status === 'complete')
+            lastCompleted = `${id.split('_').pop()}: ${task.title}`;
+        if (!nextTask && (task.status === 'not_started' || task.status === 'in_progress')) {
+            const verb = task.status === 'in_progress' ? 'continue' : 'start';
+            nextTask = `${id.split('_').pop()}: ${task.title} (${verb})`;
+        }
+    }
+    if (lastCompleted)
+        lines.push(`  Last: ${lastCompleted}`);
+    if (state.knownIssues.length > 0) {
+        lines.push(`  Issues: ${state.knownIssues.join('; ')}`);
+    }
+    if (nextTask)
+        lines.push(`  Next: ${nextTask}`);
+    if (state.stale)
+        lines.push('  ⚠ State may be stale — `ginko pull` to refresh');
+    return lines.join('\n');
+}
+//# sourceMappingURL=sprint-state.js.map