@kynetic-ai/spec 0.5.0 → 0.7.0

package/dist/cli/commands/session.js

@@ -1,1874 +1,10 @@
 /**
- * Session management commands
+ * Session management commands — barrel re-export.
  *
- * Provides context for starting/resuming work sessions.
+ * The implementation has been split into focused modules under ./session/.
+ * This file re-exports the public API for backward compatibility.
  */
-import chalk from "chalk";
-import { getReadyTasks, initContext, loadAllItems, loadAllTasks, loadInboxItems, loadSessionContext, loadTriageRecords, ReferenceIndex, } from "../../parser/index.js";
-import { ShadowError, shadowPull, } from "../../parser/shadow.js";
-import { loadMetaContext } from "../../parser/meta.js";
-import { ulid } from "ulid";
-import { getAllSessionLogSummaries, getSessionLogDetail, resolveSessionId, readEvents, readSessionContext, computeSessionLogStats, computeToolUsageStats, computeTimePeriodStats, searchSessionEvents, deduplicatePhasedToolCalls, createSessionWithBudget, validateSessionId, injectClaudeCodeEnv, injectCodexEnv, injectGeminiEnv, injectOpenCodeEnv, getFallbackInjectionInstructions, } from "../../sessions/store.js";
-import { errors, hints, sessionHeaders, sessionPrompt, } from "../../strings/index.js";
-import { formatCommitGuidance, formatRelativeTime, getCurrentBranch, getRecentCommits, getWorkingTreeStatus, isGitRepo, parseTimeSpec, } from "../../utils/index.js";
-import { markMutating } from "../command-annotations.js";
-import { EXIT_CODES } from "../exit-codes.js";
-import { error, info, isJsonMode, isNoteSuperseded, output, success, warn } from "../output.js";
-// ─── Data Gathering ──────────────────────────────────────────────────────────
-/**
- * Build a reverse dependency map: for each task ULID, count how many
- * pending tasks depend on it. Unresolvable refs are silently skipped.
- */
-function computeUnlocksMap(allTasks, index) {
-    const counts = new Map();
-    for (const task of allTasks) {
-        // Only count pending tasks as "unlockable" downstream work per spec
-        if (task.status !== "pending")
-            continue;
-        for (const depRef of task.depends_on) {
-            const result = index.resolve(depRef);
-            if (!result.ok)
-                continue; // AC: unresolvable refs silently skipped
-            const depUlid = result.item._ulid;
-            counts.set(depUlid, (counts.get(depUlid) || 0) + 1);
-        }
-    }
-    return counts;
-}
-function toActiveTaskSummary(task, index) {
-    const lastNote = task.notes.length > 0 ? task.notes[task.notes.length - 1] : null;
-    const incompleteTodos = task.todos.filter((t) => !t.done).length;
-    return {
-        ref: index.shortUlid(task._ulid),
-        slug: task.slugs.length > 0 ? task.slugs[0] : null,
-        title: task.title,
-        description: task.description || null,
-        status: task.status,
-        started_at: task.started_at || null,
-        priority: task.priority,
-        spec_ref: task.spec_ref || null,
-        note_count: task.notes.length,
-        last_note_at: lastNote ? lastNote.created_at : null,
-        todo_count: task.todos.length,
-        incomplete_todos: incompleteTodos,
-    };
-}
-function toReadyTaskSummary(task, index, unlocksMap) {
-    return {
-        ref: index.shortUlid(task._ulid),
-        slug: task.slugs.length > 0 ? task.slugs[0] : null,
-        title: task.title,
-        description: task.description || null,
-        priority: task.priority,
-        spec_ref: task.spec_ref || null,
-        tags: task.tags,
-        unlocks: unlocksMap.get(task._ulid) || 0,
-    };
-}
-function toBlockedTaskSummary(task, _allTasks, index, unlocksMap) {
-    // Find unmet dependencies
-    const unmetDeps = [];
-    for (const depRef of task.depends_on) {
-        const result = index.resolve(depRef);
-        if (result.ok) {
-            const depItem = result.item;
-            if ("status" in depItem && depItem.status !== "completed") {
-                unmetDeps.push(depRef);
-            }
-        }
-    }
-    return {
-        ref: index.shortUlid(task._ulid),
-        slug: task.slugs.length > 0 ? task.slugs[0] : null,
-        title: task.title,
-        description: task.description || null,
-        blocked_by: task.blocked_by,
-        unmet_deps: unmetDeps,
-        unlocks: unlocksMap.get(task._ulid) || 0,
-    };
-}
-function toCompletedTaskSummary(task, index) {
-    return {
-        ref: index.shortUlid(task._ulid),
-        slug: task.slugs.length > 0 ? task.slugs[0] : null,
-        title: task.title,
-        completed_at: task.completed_at || "",
-        closed_reason: task.closed_reason || null,
-        origin: task.origin,
-    };
-}
-function collectRecentNotes(tasks, index, options) {
-    const allNotes = [];
-    for (const task of tasks) {
-        // Only include notes from in_progress, pending_review, or completed tasks
-        const taskStatus = task.status;
-        if (!["in_progress", "pending_review", "needs_work", "completed"].includes(taskStatus)) {
-            continue;
-        }
-        for (const note of task.notes) {
-            const noteDate = new Date(note.created_at);
-            // Filter by since date if provided
-            if (options.since && noteDate < options.since) {
-                continue;
-            }
-            // Filter out superseded notes
-            if (isNoteSuperseded(note, task.notes)) {
-                continue;
-            }
-            allNotes.push({
-                task_ref: index.shortUlid(task._ulid),
-                task_title: task.title,
-                task_status: taskStatus,
-                note_ulid: note._ulid.slice(0, 8),
-                created_at: note.created_at,
-                author: note.author || null,
-                content: note.content,
-            });
-        }
-    }
-    // Sort by date descending, take limit
-    return allNotes
-        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
-        .slice(0, options.limit);
-}
-function collectIncompleteTodos(tasks, index, options) {
-    const allTodos = [];
-    for (const task of tasks) {
-        for (const todo of task.todos) {
-            // Only include incomplete todos
-            if (todo.done)
-                continue;
-            allTodos.push({
-                task_ref: index.shortUlid(task._ulid),
-                task_title: task.title,
-                id: todo.id,
-                text: todo.text,
-                added_at: todo.added_at,
-                added_by: todo.added_by || null,
-            });
-        }
-    }
-    // Sort by added_at descending (most recent first), take limit
-    return allTodos
-        .sort((a, b) => new Date(b.added_at).getTime() - new Date(a.added_at).getTime())
-        .slice(0, options.limit);
-}
-/**
- * Build a unified activity timeline from completed tasks and git commits.
- *
- * - Commits with Task: @slug trailers are matched to completed tasks and shown
- *   as combined "linked_commit" entries (AC: ac-activity-trailer-link, ac-activity-dedup)
- * - Unlinked commits appear as standalone "commit" entries
- * - Tasks not linked to any commit appear as standalone "task_completion" entries
- * - All items sorted most recent first (AC: ac-activity-sort)
- *
- * @param completedTasks - Completed task summaries
- * @param commits - Recent commit summaries (with task_refs parsed from trailers)
- * @param taskRefResolver - Maps a trailer ref (slug or ULID prefix) to a completed task's ref (short ULID)
- */
-function buildActivityTimeline(completedTasks, commits, taskRefResolver) {
-    const items = [];
-    // Build lookup from short ULID ref to CompletedTaskSummary
-    const taskByRef = new Map();
-    for (const task of completedTasks) {
-        taskByRef.set(task.ref, task);
-    }
-    // Track which tasks have been linked to a commit (for dedup)
-    const linkedTaskRefs = new Set();
-    for (const commit of commits) {
-        if (commit.task_refs.length > 0) {
-            let linkedTask;
-            for (const trailerRef of commit.task_refs) {
-                // Resolve the trailer ref (slug or ULID) to the short ULID ref
-                const resolvedRef = taskRefResolver.get(trailerRef);
-                if (resolvedRef) {
-                    linkedTask = taskByRef.get(resolvedRef);
-                }
-                // Also try direct match on short ULID ref
-                if (!linkedTask) {
-                    linkedTask = taskByRef.get(trailerRef);
-                }
-                if (linkedTask) {
-                    linkedTaskRefs.add(linkedTask.ref);
-                    // Use the later of commit date and task completion date for sort accuracy
-                    const commitTime = new Date(commit.date).getTime();
-                    const taskTime = new Date(linkedTask.completed_at).getTime();
-                    const laterDate = taskTime > commitTime ? linkedTask.completed_at : commit.date;
-                    items.push({
-                        type: "linked_commit",
-                        date: laterDate,
-                        commit,
-                        task: linkedTask,
-                    });
-                    break; // One linked entry per commit
-                }
-            }
-            if (!linkedTask) {
-                // Task ref in trailer but no matching completed task found
-                items.push({ type: "commit", date: commit.date, commit });
-            }
-        }
-        else {
-            items.push({ type: "commit", date: commit.date, commit });
-        }
-    }
-    // Add task completions not already linked to a commit
-    for (const task of completedTasks) {
-        if (!linkedTaskRefs.has(task.ref)) {
-            items.push({
-                type: "task_completion",
-                date: task.completed_at,
-                task,
-            });
-        }
-    }
-    // AC: @session-start-activity-timeline ac-activity-sort
-    // Sort most recent first
-    items.sort((a, b) => new Date(b.date).getTime() - new Date(a.date).getTime());
-    return items;
-}
-/**
- * Gather session context data
- */
-export async function gatherSessionContext(ctx, options) {
-    const limit = parseInt(options.limit || "10", 10);
-    const sinceDate = options.since ? parseTimeSpec(options.since) : null;
-    const showGit = options.git !== false; // default true
-    // Load all data
-    const allTasks = await loadAllTasks(ctx);
-    const items = await loadAllItems(ctx);
-    const inboxItems = await loadInboxItems(ctx);
-    const triageRecords = await loadTriageRecords(ctx);
-    const index = new ReferenceIndex(allTasks, items);
-    // AC: @session-start-inbox-triage ac-inbox-untriaged-def
-    // Build lookup: inbox ULID → triage record (most recent if multiple)
-    const triageByInboxRef = new Map();
-    for (const record of triageRecords) {
-        triageByInboxRef.set(record.inbox_ref, { action: record.action });
-    }
-    // Compute stats
-    const stats = {
-        total_tasks: allTasks.length,
-        in_progress: allTasks.filter((t) => t.status === "in_progress").length,
-        needs_work: allTasks.filter((t) => t.status === "needs_work").length,
-        pending_review: allTasks.filter((t) => t.status === "pending_review")
-            .length,
-        ready: getReadyTasks(allTasks).length,
-        blocked: allTasks.filter((t) => t.status === "blocked").length,
-        completed: allTasks.filter((t) => t.status === "completed").length,
-        inbox_items: inboxItems.length,
-    };
-    // Get active tasks (in_progress + needs_work, optionally filtered to automation-eligible only)
-    // AC: @cli-ralph ac-16
-    const activeTasks = allTasks
-        .filter((t) => t.status === "in_progress" || t.status === "needs_work")
-        .filter((t) => !options.eligible || t.automation === "eligible")
-        .sort((a, b) => a.priority - b.priority)
-        .slice(0, options.full ? undefined : limit)
-        .map((t) => toActiveTaskSummary(t, index));
-    // Get pending review tasks
-    const pendingReviewTasks = allTasks
-        .filter((t) => t.status === "pending_review")
-        .sort((a, b) => a.priority - b.priority)
-        .slice(0, options.full ? undefined : limit)
-        .map((t) => toActiveTaskSummary(t, index));
-    // Get recent notes from active, pending_review, and recently completed tasks
-    // AC: @cmd-session-start ac-1, ac-2
-    // Collect notes per-status first to prevent one status from starving others
-    const noteLimitPerStatus = options.full ? limit : Math.ceil(limit / 3);
-    const inProgressNotes = collectRecentNotes(allTasks.filter((t) => t.status === "in_progress" || t.status === "needs_work"), index, { limit: noteLimitPerStatus, since: sinceDate });
-    const pendingReviewNotes = collectRecentNotes(allTasks.filter((t) => t.status === "pending_review"), index, { limit: noteLimitPerStatus, since: sinceDate });
-    const recentlyCompletedForNotes = allTasks
-        .filter((t) => t.status === "completed" && t.completed_at)
-        .sort((a, b) => {
-        const aDate = new Date(a.completed_at || 0);
-        const bDate = new Date(b.completed_at || 0);
-        return bDate.getTime() - aDate.getTime();
-    })
-        .slice(0, 5); // Last 3-5 completed tasks per AC-2
-    const completedNotes = collectRecentNotes(recentlyCompletedForNotes, index, { limit: noteLimitPerStatus, since: sinceDate });
-    // Combine notes from all statuses, preserving representation from each
-    const recentNotes = [...inProgressNotes, ...pendingReviewNotes, ...completedNotes]
-        .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime());
-    // Get incomplete todos from active tasks
-    const activeTodos = collectIncompleteTodos(allTasks.filter((t) => t.status === "in_progress" || t.status === "needs_work"), index, { limit: options.full ? limit * 2 : limit });
-    // Compute reverse dependency map for "unlocks N" annotations
-    const unlocksMap = computeUnlocksMap(allTasks, index);
-    // AC: @cmd-session-start ac-primer-default, ac-full-sections
-    // Primer: top 5 ready tasks; Full: all ready tasks
-    // Respect --limit as upper bound when provided
-    const readyLimit = options.full ? undefined : Math.min(limit, 5);
-    const readyTasks = getReadyTasks(allTasks)
-        .filter((t) => !options.eligible || t.automation === "eligible")
-        .slice(0, readyLimit)
-        .map((t) => toReadyTaskSummary(t, index, unlocksMap));
-    // Get blocked tasks
-    const blockedTasks = allTasks
-        .filter((t) => t.status === "blocked")
-        .slice(0, options.full ? undefined : limit)
-        .map((t) => toBlockedTaskSummary(t, allTasks, index, unlocksMap));
-    // Get recently completed tasks
-    const recentlyCompleted = allTasks
-        .filter((t) => {
-        if (t.status !== "completed" || !t.completed_at)
-            return false;
-        const completedDate = new Date(t.completed_at);
-        if (sinceDate && completedDate < sinceDate)
-            return false;
-        return true;
-    })
-        .sort((a, b) => {
-        // Sort by completed_at descending (most recent first)
-        const aDate = new Date(a.completed_at || 0);
-        const bDate = new Date(b.completed_at || 0);
-        return bDate.getTime() - aDate.getTime();
-    })
-        .slice(0, options.full ? undefined : limit)
-        .map((t) => toCompletedTaskSummary(t, index));
-    // Get git info
-    let branch = null;
-    let recentCommits = [];
-    let workingTree = null;
-    if (showGit && isGitRepo(ctx.rootDir)) {
-        branch = getCurrentBranch(ctx.rootDir);
-        const commits = getRecentCommits({
-            limit: options.full ? limit * 2 : limit,
-            since: sinceDate || undefined,
-            cwd: ctx.rootDir,
-        });
-        recentCommits = commits.map((c) => ({
-            hash: c.hash,
-            full_hash: c.fullHash,
-            date: c.date.toISOString(),
-            message: c.message,
-            author: c.author,
-            task_refs: c.taskRefs,
-        }));
-        workingTree = getWorkingTreeStatus(ctx.rootDir);
-    }
-    // Get inbox items with triage status (oldest first to encourage triage)
-    // AC: @session-start-inbox-triage ac-inbox-untriaged-def
-    const allInboxSummaries = inboxItems
-        .sort((a, b) => new Date(a.created_at).getTime() - new Date(b.created_at).getTime())
-        .map((item) => {
-        const triageInfo = triageByInboxRef.get(item._ulid);
-        return {
-            ref: item._ulid.slice(0, 8),
-            text: item.text,
-            created_at: item.created_at,
-            tags: item.tags,
-            added_by: item.added_by || null,
-            triaged: !!triageInfo,
-            triage_action: triageInfo?.action ?? null,
-        };
-    });
-    // AC: @session-start-inbox-triage ac-inbox-stat-line, ac-inbox-all-triaged
-    const inboxStats = {
-        total: allInboxSummaries.length,
-        untriaged: allInboxSummaries.filter((i) => !i.triaged).length,
-        deferred: allInboxSummaries.filter((i) => i.triage_action === "defer")
-            .length,
-        triaged: allInboxSummaries.filter((i) => i.triaged).length,
-    };
-    // JSON always gets full list with triage status; human display filters in formatSessionContext
-    const inboxSummaries = allInboxSummaries;
-    // Load session context (focus, threads, questions)
-    const sessionContext = await loadSessionContext(ctx);
-    // Build task ref resolver for activity timeline: maps slug/ULID to short ref
-    // This allows commits with Task: @task-slug trailers to match completed tasks
-    const taskRefResolver = new Map();
-    for (const task of allTasks) {
-        if (task.status !== "completed")
-            continue;
-        const shortRef = index.shortUlid(task._ulid);
-        // Map each slug to the short ref
-        for (const slug of task.slugs) {
-            taskRefResolver.set(slug, shortRef);
-        }
-        // Also map the full ULID and short ULID to itself
-        taskRefResolver.set(task._ulid, shortRef);
-        taskRefResolver.set(shortRef, shortRef);
-    }
-    // Build unified activity timeline
-    // AC: @session-start-activity-timeline ac-activity-merge
-    // AC: @cmd-session-start ac-primer-default, ac-full-sections
-    // Primer: 10 items; Full: 20 items
-    // Respect --limit as upper bound when provided
-    const activityLimit = options.full ? Math.min(limit * 2, 20) : Math.min(limit, 10);
-    const activityTimeline = buildActivityTimeline(recentlyCompleted, recentCommits, taskRefResolver).slice(0, activityLimit);
-    // AC: @cmd-session-start ac-full-sections — observations section (full mode only)
-    let observations = [];
-    if (options.full) {
-        const metaCtx = await loadMetaContext(ctx);
-        observations = metaCtx.observations
-            .filter((o) => !o.resolved)
-            .sort((a, b) => new Date(b.created_at).getTime() - new Date(a.created_at).getTime())
-            .map((o) => ({
-            ref: o._ulid.slice(0, 8),
-            type: o.type,
-            content: o.content,
-            created_at: o.created_at,
-            author: o.author || null,
-            resolved: o.resolved,
-            workflow_ref: o.workflow_ref || null,
-        }));
-    }
-    // AC: @session-start-computed-json ac-computed-unlocks
-    // Build task_unlocks map: short ULID ref → count of pending dependents
-    const taskUnlocks = {};
-    for (const [taskUlid, count] of unlocksMap) {
-        if (count > 0) {
-            taskUnlocks[index.shortUlid(taskUlid)] = count;
-        }
-    }
-    // AC: @session-start-computed-json ac-computed-inbox, ac-computed-unlocks, ac-computed-activity
-    const computed = {
-        inbox_untriaged_count: inboxStats.untriaged,
-        inbox_deferred_count: inboxStats.deferred,
-        inbox_total: inboxStats.total,
-        task_unlocks: taskUnlocks,
-        recent_activity: activityTimeline,
-    };
-    return {
-        generated_at: new Date().toISOString(),
-        branch,
-        context: sessionContext,
-        active_tasks: activeTasks,
-        pending_review_tasks: pendingReviewTasks,
-        recent_notes: recentNotes,
-        active_todos: activeTodos,
-        ready_tasks: readyTasks,
-        blocked_tasks: blockedTasks,
-        recently_completed: recentlyCompleted,
-        recent_commits: recentCommits,
-        activity_timeline: activityTimeline,
-        working_tree: workingTree,
-        inbox_items: inboxSummaries,
-        inbox_stats: inboxStats,
-        observations,
-        stats,
-        computed,
-    };
-}
-/**
- * Get iteration stats - tasks completed/started since a given time.
- * AC: @ralph-task-limit ac-detection
- */
-export async function getIterationStats(ctx, since) {
-    const allTasks = await loadAllTasks(ctx);
-    // Count both completed and pending_review (submitted) tasks toward the limit.
-    // Submit means the agent's work is done — it should count the same as complete.
-    // AC: @ralph-task-limit ac-detection
-    const completedSince = allTasks.filter((t) => {
-        if (t.status === "completed" && t.completed_at) {
-            return new Date(t.completed_at) >= since;
-        }
-        if (t.status === "pending_review" && t.submitted_at) {
-            return new Date(t.submitted_at) >= since;
-        }
-        return false;
-    });
-    const startedSince = allTasks.filter((t) => {
-        if (!t.started_at)
-            return false;
-        return new Date(t.started_at) >= since;
-    });
-    // Use first slug or ULID prefix as ref
-    const getRef = (t) => t.slugs.length > 0 ? `@${t.slugs[0]}` : `@${t._ulid.slice(0, 8)}`;
-    return {
-        tasks_completed: completedSince.length,
-        tasks_started: startedSince.length,
-        completed_refs: completedSince.map(getRef),
-    };
-}
-/**
- * Perform session checkpoint - check for uncommitted work before ending session.
- *
- * This is designed for use as a Claude Code stop hook. It checks for:
- * - Uncommitted git changes (staged, unstaged, untracked)
- * - Tasks in in_progress status
- * - Incomplete todos on active tasks
- *
- * Returns a structured result indicating whether the session can end cleanly.
- */
-export async function performCheckpoint(ctx, options) {
-    const issues = [];
-    const instructions = [];
-    // Load tasks
-    const allTasks = await loadAllTasks(ctx);
-    // Check for in-progress tasks
-    const inProgressTasks = allTasks.filter((t) => t.status === "in_progress");
-    for (const task of inProgressTasks) {
-        const ref = task.slugs[0]
-            ? `@${task.slugs[0]}`
-            : `@${task._ulid.slice(0, 8)}`;
-        issues.push({
-            type: "in_progress_task",
-            description: `Task ${ref} is still in progress: ${task.title}`,
-            details: {
-                ref,
-                title: task.title,
-                started_at: task.started_at,
-            },
-        });
-        // Check for incomplete todos on this task
-        const incompleteTodos = task.todos.filter((t) => !t.done);
-        for (const todo of incompleteTodos) {
-            issues.push({
-                type: "incomplete_todo",
-                description: `Incomplete todo on ${ref}: ${todo.text}`,
-                details: {
-                    task_ref: ref,
-                    todo_id: todo.id,
-                    text: todo.text,
-                },
-            });
-        }
-    }
-    // Check for uncommitted git changes
-    if (isGitRepo(ctx.rootDir)) {
-        const workingTree = getWorkingTreeStatus(ctx.rootDir);
-        if (!workingTree.clean) {
-            const changeCount = workingTree.staged.length +
-                workingTree.unstaged.length +
-                workingTree.untracked.length;
-            issues.push({
-                type: "uncommitted_changes",
-                description: `${changeCount} uncommitted changes in working tree`,
-                details: {
-                    staged: workingTree.staged.length,
-                    unstaged: workingTree.unstaged.length,
-                    untracked: workingTree.untracked.length,
-                },
-            });
-        }
-    }
-    // Build instructions based on issues
-    if (issues.length > 0 && !options.force) {
-        instructions.push("If you've been instructed to ignore this message or are working on");
-        instructions.push("unrelated things to any in progress tasks then disregard this message,");
-        instructions.push("otherwise before ending this session, please:");
-        const hasInProgress = issues.some((i) => i.type === "in_progress_task");
-        const hasUncommitted = issues.some((i) => i.type === "uncommitted_changes");
-        const hasIncompleteTodos = issues.some((i) => i.type === "incomplete_todo");
-        let step = 1;
-        if (hasInProgress) {
-            instructions.push(`${step++}. Read in-progress task notes to get full context of the current task status`);
-            instructions.push(`${step++}. Add notes documenting current state if any context is missing from this session`);
-            instructions.push(`${step++}. Complete the task if you've completed the objectives and no AC are left uncovered\notherwise leave it in progress for a future session`);
-        }
-        if (hasIncompleteTodos) {
-            instructions.push(`${step++}. Complete or acknowledge incomplete todos on active tasks`);
-        }
-        if (hasUncommitted) {
-            instructions.push(`${step++}. Commit your changes with a descriptive message`);
-            // Add WIP commit guidance if there are in-progress tasks
-            if (inProgressTasks.length > 0) {
-                const task = inProgressTasks[0];
-                const guidance = formatCommitGuidance(task, { wip: true });
-                instructions.push("");
-                instructions.push("Suggested WIP commit:");
-                instructions.push(`  ${guidance.message}`);
-                instructions.push("");
-                for (const trailer of guidance.trailers) {
-                    instructions.push(`  ${trailer}`);
-                }
-            }
-        }
-        instructions.push("");
-        instructions.push("Use: kspec task @task to get current task state");
-        instructions.push('Use: kspec task note @task "Progress notes..." to document state');
-        instructions.push('Use: kspec task complete @task --reason "Summary" if task is done');
-    }
-    // Allow stop if:
-    // - No issues found
-    // - --force flag passed
-    // - This is a retry (stop_hook_active = true from previous block)
-    const isRetry = options.stopHookActive === true;
-    const ok = issues.length === 0 || options.force === true || isRetry;
-    let message;
-    if (isRetry && issues.length > 0) {
-        message = `[kspec] Session checkpoint: ${issues.length} issue(s) acknowledged - allowing stop`;
-    }
-    else if (ok) {
-        message = "[kspec] Session checkpoint passed - ready to end session";
-    }
-    else {
-        message = `[kspec] Session checkpoint: ${issues.length} issue(s) need attention`;
-    }
-    return {
-        ok,
-        message,
-        issues,
-        instructions,
-    };
-}
-// ─── Output Formatting ───────────────────────────────────────────────────────
-function formatCheckpointResult(result) {
-    if (result.ok) {
-        console.log(chalk.green(result.message));
-    }
-    else {
-        console.log(chalk.yellow(result.message));
-        console.log("");
-        for (const issue of result.issues) {
-            const icon = issue.type === "uncommitted_changes"
-                ? chalk.yellow("⚠")
-                : issue.type === "in_progress_task"
-                    ? chalk.blue("●")
-                    : chalk.gray("○");
-            console.log(`  ${icon} ${issue.description}`);
-        }
-        if (result.instructions.length > 0) {
-            console.log("");
-            for (const instruction of result.instructions) {
-                console.log(chalk.gray(instruction));
-            }
-        }
-    }
-}
-function formatSessionContext(ctx, options) {
-    const isFull = !!options.full;
-    // AC: @cmd-session-start ac-slug-display, ac-slug-fallback
-    // Display ref as @slug when available, @short-ulid when not
-    const displayRef = (task) => task.slug ? `@${task.slug}` : `@${task.ref}`;
-    // Header
-    console.log(`\n${sessionHeaders.title}`);
-    const age = formatRelativeTime(new Date(ctx.generated_at));
-    if (ctx.branch) {
-        console.log(chalk.gray(`Branch: ${ctx.branch} | Generated: ${age}`));
-    }
-    else {
-        console.log(chalk.gray(`Generated: ${age}`));
-    }
-    // Stats summary
-    const pendingReviewNote = ctx.stats.pending_review > 0
-        ? `${ctx.stats.pending_review} awaiting review, `
-        : "";
-    const inboxNote = ctx.stats.inbox_items > 0 ? ` | Inbox: ${ctx.stats.inbox_items}` : "";
-    console.log(chalk.gray(`Tasks: ${ctx.stats.in_progress} active, ${pendingReviewNote}${ctx.stats.ready} ready, ` +
-        `${ctx.stats.blocked} blocked, ${ctx.stats.completed}/${ctx.stats.total_tasks} completed${inboxNote}`));
-    // Session context section (focus, threads, questions)
-    if (ctx.context &&
-        (ctx.context.focus ||
-            ctx.context.threads.length > 0 ||
-            ctx.context.open_questions.length > 0)) {
-        console.log("\n--- Session Context ---");
-        if (ctx.context.focus) {
-            console.log(`  ${chalk.cyan("Focus:")} ${ctx.context.focus}`);
-        }
-        if (ctx.context.threads.length > 0) {
-            console.log(`  ${chalk.cyan("Active Threads:")}`);
-            for (const thread of ctx.context.threads) {
-                console.log(`    - ${thread}`);
-            }
-        }
-        if (ctx.context.open_questions.length > 0) {
-            console.log(`  ${chalk.cyan("Open Questions:")}`);
-            for (const question of ctx.context.open_questions) {
-                console.log(`    - ${question}`);
-            }
-        }
-    }
-    // ── Section ordering per AC: @cmd-session-start ac-section-order ──
-    // active tasks → pending review → blocked → ready → recent activity → inbox → working tree → quick commands
-    // AC: @cmd-session-start ac-empty-skip — empty sections omitted entirely
-    // ── Active tasks section ──
-    // AC: @cmd-session-start ac-active-detail, ac-needs-work-indicator
-    if (ctx.active_tasks.length > 0) {
-        console.log(`\n${sessionHeaders.activeWork}`);
-        // Collect notes relevant to active tasks for inline display
-        const activeTaskNotes = ctx.recent_notes.filter((n) => n.task_status === "in_progress" || n.task_status === "needs_work");
-        for (const task of ctx.active_tasks) {
-            const started = task.started_at
-                ? chalk.gray(` (started ${formatRelativeTime(new Date(task.started_at))})`)
-                : "";
-            const priority = task.priority <= 2
-                ? chalk.red(`P${task.priority}`)
-                : chalk.gray(`P${task.priority}`);
-            // AC: @cmd-session-start ac-needs-work-indicator
-            const statusLabel = task.status === "needs_work"
-                ? chalk.red("[needs_work]")
-                : chalk.blue("[in_progress]");
-            console.log(`  ${statusLabel} ${priority} ${displayRef(task)} ${task.title}${started}`);
-            // AC: @cmd-session-start ac-active-detail — show description
-            if (task.description) {
-                console.log(chalk.gray(`    ${task.description}`));
-            }
-            // AC: @cmd-session-start ac-active-detail — show recent notes inline
-            const taskNotes = activeTaskNotes.filter((n) => n.task_ref === task.ref);
-            if (taskNotes.length > 0) {
-                const latestNote = taskNotes[0]; // already sorted most recent first
-                const noteAge = formatRelativeTime(new Date(latestNote.created_at));
-                const author = latestNote.author
-                    ? chalk.gray(` by ${latestNote.author}`)
-                    : "";
-                console.log(`    ${chalk.yellow("Note")} ${chalk.gray(`(${noteAge}${author})`)}`);
-                let content = latestNote.content.trim();
-                if (!isFull && content.length > 200) {
-                    content = `${content.slice(0, 200).trim()}...`;
-                }
-                const lines = content.split("\n");
-                const maxLines = isFull ? lines.length : 3;
-                for (const line of lines.slice(0, maxLines)) {
-                    console.log(`      ${chalk.white(line)}`);
-                }
-                if (!isFull && lines.length > maxLines) {
-                    console.log(chalk.gray(`      ... (${lines.length - maxLines} more lines)`));
-                }
-            }
-        }
-    }
-    // ── Awaiting review section ──
-    // AC: @cmd-session-start ac-review-detail
-    if (ctx.pending_review_tasks.length > 0) {
-        console.log(`\n${sessionHeaders.awaitingReview}`);
-        const reviewNotes = ctx.recent_notes.filter((n) => n.task_status === "pending_review");
-        for (const task of ctx.pending_review_tasks) {
-            const priority = task.priority <= 2
-                ? chalk.red(`P${task.priority}`)
-                : chalk.gray(`P${task.priority}`);
-            console.log(`  ${chalk.yellow("[pending_review]")} ${priority} ${displayRef(task)} ${task.title}`);
-            // AC: @cmd-session-start ac-review-detail — show recent notes
-            const taskNotes = reviewNotes.filter((n) => n.task_ref === task.ref);
-            if (taskNotes.length > 0) {
-                const latestNote = taskNotes[0];
-                const noteAge = formatRelativeTime(new Date(latestNote.created_at));
-                const author = latestNote.author
-                    ? chalk.gray(` by ${latestNote.author}`)
-                    : "";
-                console.log(`    ${chalk.yellow("Note")} ${chalk.gray(`(${noteAge}${author})`)}`);
-                let content = latestNote.content.trim();
-                if (!isFull && content.length > 200) {
-                    content = `${content.slice(0, 200).trim()}...`;
-                }
-                const lines = content.split("\n");
-                const maxLines = isFull ? lines.length : 3;
-                for (const line of lines.slice(0, maxLines)) {
-                    console.log(`      ${chalk.white(line)}`);
-                }
-                if (!isFull && lines.length > maxLines) {
-                    console.log(chalk.gray(`      ... (${lines.length - maxLines} more lines)`));
-                }
-            }
-        }
-    }
-    // ── Blocked tasks section ──
-    if (ctx.blocked_tasks.length > 0) {
-        console.log(`\n${sessionHeaders.blocked}`);
-        for (const task of ctx.blocked_tasks) {
-            const unlocks = task.unlocks > 0 ? chalk.green(` unlocks ${task.unlocks}`) : "";
-            console.log(`  ${chalk.red("[blocked]")} ${displayRef(task)} ${task.title}${unlocks}`);
-            if (task.blocked_by.length > 0) {
-                console.log(chalk.gray(`    Blockers: ${task.blocked_by.join(", ")}`));
-            }
-            if (task.unmet_deps.length > 0) {
-                console.log(chalk.gray(`    Waiting on: ${task.unmet_deps.join(", ")}`));
-            }
-        }
-    }
-    // ── Ready tasks section ──
-    if (ctx.ready_tasks.length > 0) {
-        console.log(`\n${sessionHeaders.readyTasks}`);
-        for (const task of ctx.ready_tasks) {
-            const priority = task.priority <= 2
-                ? chalk.red(`P${task.priority}`)
-                : chalk.gray(`P${task.priority}`);
-            const tags = task.tags.length > 0 ? chalk.cyan(` #${task.tags.join(" #")}`) : "";
-            const unlocks = task.unlocks > 0 ? chalk.green(` unlocks ${task.unlocks}`) : "";
-            console.log(`  ${priority} ${displayRef(task)} ${task.title}${unlocks}${tags}`);
-        }
-    }
-    // ── Recent Activity timeline ──
-    // AC: @session-start-activity-timeline ac-activity-merge
-    if (ctx.activity_timeline.length > 0) {
-        console.log(`\n${sessionHeaders.recentActivity}`);
-        const observationPromotedTasks = [];
-        const taskGroups = new Map();
-        const groups = [];
-        for (const item of ctx.activity_timeline) {
-            if (item.type === "linked_commit") {
-                const key = item.task.ref;
-                let group = taskGroups.get(key);
-                if (!group) {
-                    group = { task: item.task, commits: [], sortDate: item.date };
-                    taskGroups.set(key, group);
-                }
-                group.commits.push({ commit: item.commit, date: item.commit.date });
-                // Update sortDate to the most recent event in the group
-                if (new Date(item.date).getTime() > new Date(group.sortDate).getTime()) {
-                    group.sortDate = item.date;
-                }
-            }
-            else if (item.type === "task_completion") {
-                groups.push({ kind: "task_completion", task: item.task, date: item.date });
-            }
-            else if (item.type === "commit") {
-                groups.push({ kind: "orphan_commit", commit: item.commit, date: item.date });
-            }
-        }
-        // Add task groups to the groups array
-        for (const group of taskGroups.values()) {
-            // AC: @session-start-activity-timeline ac-activity-sort
-            // Sort commits within a group chronologically (oldest first)
-            group.commits.sort((a, b) => new Date(a.date).getTime() - new Date(b.date).getTime());
-            groups.push({ kind: "task_group", ...group });
-        }
-        // AC: @session-start-activity-timeline ac-activity-sort
-        // Sort groups by most recent event, most recent first
-        groups.sort((a, b) => new Date(b.kind === "task_group" ? b.sortDate : b.date).getTime() -
-            new Date(a.kind === "task_group" ? a.sortDate : a.date).getTime());
-        for (const group of groups) {
-            if (group.kind === "task_completion") {
-                // Standalone completed task (not linked to any commit)
-                let reason = "";
-                if (group.task.closed_reason) {
-                    const maxLen = isFull ? 120 : 60;
-                    const truncated = group.task.closed_reason.length > maxLen
-                        ? `${group.task.closed_reason.slice(0, maxLen).trim()}...`
-                        : group.task.closed_reason;
-                    reason = chalk.gray(` - ${truncated}`);
-                }
-                // AC: @cmd-session-start ac-slug-display
-                const taskDisplay = group.task.slug
-                    ? `@${group.task.slug}`
-                    : `@${group.task.ref}`;
-                // AC: @cmd-session-start ac-relative-time-human
-                const itemAge = formatRelativeTime(new Date(group.date));
-                console.log(`  ${chalk.green("✓")} ${taskDisplay} ${group.task.title} ${chalk.gray(`(${itemAge})`)}${reason}`);
-                if (group.task.origin === "observation_promotion") {
-                    observationPromotedTasks.push(taskDisplay);
-                }
-            }
-            else if (group.kind === "task_group") {
-                // AC: @session-start-activity-timeline ac-activity-hierarchy, ac-activity-trailer-link
-                // Task as top-level entry with linked commits nested beneath
-                const taskDisplay = group.task.slug
-                    ? `@${group.task.slug}`
-                    : `@${group.task.ref}`;
-                const groupAge = formatRelativeTime(new Date(group.sortDate));
-                console.log(`  ${chalk.green("✓")} ${taskDisplay} ${group.task.title} ${chalk.gray(`(${groupAge})`)}`);
-                if (group.task.origin === "observation_promotion") {
-                    observationPromotedTasks.push(taskDisplay);
-                }
-                // Render nested commits with visual connectors
-                for (let i = 0; i < group.commits.length; i++) {
-                    const { commit, date } = group.commits[i];
-                    const isLast = i === group.commits.length - 1;
-                    const connector = isLast ? "└─" : "├─";
-                    const commitAge = formatRelativeTime(new Date(date));
-                    console.log(`    ${chalk.gray(connector)} ${chalk.yellow(commit.hash)} ${commit.message} ${chalk.gray(`(${commitAge}, ${commit.author})`)}`);
-                }
-            }
-            else if (group.kind === "orphan_commit") {
-                // AC: @session-start-activity-timeline ac-activity-orphan
-                // Orphan commit: visually distinct from task entries
-                const commitAge = formatRelativeTime(new Date(group.date));
-                console.log(`  ${chalk.gray("○")} ${chalk.yellow(group.commit.hash)} ${group.commit.message} ${chalk.gray(`(${commitAge}, ${group.commit.author})`)}`);
-            }
-        }
-        // Show reminder about resolving observations
-        if (observationPromotedTasks.length > 0) {
-            console.log(chalk.yellow(`\n  ℹ Consider resolving linked observations: ${observationPromotedTasks.join(", ")}`));
-            console.log(chalk.gray(`    Run: kspec meta observations --pending-resolution`));
-        }
-    }
-    // ── Inbox section ──
-    // AC: @session-start-inbox-triage ac-inbox-stat-line, ac-inbox-full-list, ac-inbox-all-triaged
-    if (ctx.inbox_stats.total > 0) {
-        console.log(`\n${sessionHeaders.inbox}`);
-        // Stat line always shown (primer and full)
-        const statParts = [
-            `${ctx.inbox_stats.untriaged} untriaged`,
-            `${ctx.inbox_stats.deferred} deferred`,
-            `${ctx.inbox_stats.total} total`,
-        ];
-        console.log(`  ${statParts.join(" | ")}`);
-        // AC: @cmd-session-start ac-full-sections, @session-start-inbox-triage ac-inbox-full-list
-        // Full mode: list untriaged items (up to 20)
-        // AC: @cmd-session-start ac-slug-fallback — inbox uses @short-ulid
-        const untriagedItems = ctx.inbox_items
-            .filter((i) => !i.triaged)
-            .slice(0, 20);
-        if (isFull && untriagedItems.length > 0) {
-            console.log("");
-            for (const item of untriagedItems) {
-                const itemAge = formatRelativeTime(new Date(item.created_at));
-                const author = item.added_by ? ` by ${item.added_by}` : "";
-                const tags = item.tags.length > 0
-                    ? chalk.cyan(` [${item.tags.join(", ")}]`)
-                    : "";
-                console.log(`  ${chalk.magenta(`@${item.ref}`)} ${chalk.gray(`(${itemAge}${author})`)}${tags}`);
-                console.log(`    ${item.text}`);
-            }
-        }
-        if (ctx.inbox_stats.untriaged > 0) {
-            console.log(`  ${hints.inboxTriage}`);
-        }
-    }
-    // ── Observations section (full mode only) ──
-    // AC: @cmd-session-start ac-full-sections
-    if (isFull && ctx.observations.length > 0) {
-        console.log(`\n${chalk.yellow.bold("--- Observations (unresolved) ---")}`);
-        for (const obs of ctx.observations) {
-            const obsAge = formatRelativeTime(new Date(obs.created_at));
-            const author = obs.author ? ` by ${obs.author}` : "";
-            const typeLabel = chalk.cyan(`[${obs.type}]`);
-            console.log(`  ${typeLabel} ${chalk.gray(`@${obs.ref}`)} ${chalk.gray(`(${obsAge}${author})`)}`);
-            console.log(`    ${obs.content}`);
-        }
-    }
-    // ── Session metadata section (full mode only) ──
-    // AC: @cmd-session-start ac-full-sections
-    if (isFull &&
-        ctx.context &&
-        ctx.context.updated_at) {
-        console.log(`\n${chalk.gray.bold("--- Session Metadata ---")}`);
-        console.log(chalk.gray(`  Last updated: ${formatRelativeTime(new Date(ctx.context.updated_at))}`));
-    }
-    // ── Working tree section ──
-    // AC: @cmd-session-start ac-dirty-tree-only — only shown when dirty
-    if (ctx.working_tree && !ctx.working_tree.clean) {
-        console.log(`\n${sessionHeaders.workingTree}`);
-        if (ctx.working_tree.staged.length > 0) {
-            console.log(chalk.green("  Staged:"));
-            for (const file of ctx.working_tree.staged) {
-                console.log(`    ${chalk.green(file.status[0].toUpperCase())} ${file.path}`);
-            }
-        }
-        if (ctx.working_tree.unstaged.length > 0) {
-            console.log(chalk.red("  Modified:"));
-            for (const file of ctx.working_tree.unstaged) {
-                console.log(`    ${chalk.red(file.status[0].toUpperCase())} ${file.path}`);
-            }
-        }
-        if (ctx.working_tree.untracked.length > 0) {
-            console.log(chalk.gray("  Untracked:"));
-            const untrackedLimit = isFull
-                ? ctx.working_tree.untracked.length
-                : 5;
-            for (const filePath of ctx.working_tree.untracked.slice(0, untrackedLimit)) {
-                console.log(`    ${chalk.gray("?")} ${filePath}`);
-            }
-            if (!isFull && ctx.working_tree.untracked.length > untrackedLimit) {
-                console.log(chalk.gray(`    ... and ${ctx.working_tree.untracked.length - untrackedLimit} more`));
-            }
-        }
-    }
-    // ── Quick Commands section ──
-    const quickCommands = [];
-    if (ctx.active_tasks.length > 0) {
-        const ref = displayRef(ctx.active_tasks[0]);
-        quickCommands.push(`kspec task note ${ref} "Progress..."  ${chalk.gray("# document work")}`);
-        quickCommands.push(`kspec task complete ${ref} --reason "..."  ${chalk.gray("# finish task")}`);
-    }
-    else if (ctx.ready_tasks.length > 0) {
-        const ref = displayRef(ctx.ready_tasks[0]);
-        quickCommands.push(`kspec task start ${ref}  ${chalk.gray("# begin work")}`);
-    }
-    if (ctx.inbox_stats.untriaged > 0) {
-        quickCommands.push(`kspec triage inbox  ${chalk.gray("# triage untriaged inbox items")}`);
-    }
-    if (ctx.working_tree && !ctx.working_tree.clean) {
-        quickCommands.push(`git add . && git commit -m "..."  ${chalk.gray("# commit changes")}`);
-    }
-    if (quickCommands.length > 0) {
-        console.log(`\n${sessionHeaders.quickCommands}`);
-        for (const hint of quickCommands) {
-            console.log(`  ${hint}`);
-        }
-    }
-    console.log(""); // Final newline
-}
-// ─── Command Registration ────────────────────────────────────────────────────
-async function sessionStartAction(options) {
-    try {
-        const ctx = await initContext();
-        // AC: @shadow-sync ac-2 - Pull remote changes before showing session context
-        let syncResult = null;
-        if (ctx.shadow?.enabled) {
-            syncResult = await shadowPull(ctx.shadow.worktreeDir);
-            // AC: @shadow-sync ac-3 - Warn about conflicts but continue with local state
-            if (syncResult.hadConflict) {
-                warn("Shadow sync conflict detected. Run `kspec shadow resolve` to fix.");
-                info("Continuing with local state...");
-            }
-            else if (syncResult.pulled) {
-                info("Synced shadow branch from remote");
-            }
-        }
-        const sessionCtx = await gatherSessionContext(ctx, options);
-        output(sessionCtx, () => formatSessionContext(sessionCtx, options));
-    }
-    catch (err) {
-        error(errors.failures.gatherSessionContext, err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-/**
- * Read stdin if available (non-blocking check for hook input)
- */
-async function readStdinIfAvailable() {
-    // Check if stdin is a TTY (interactive) - if so, don't try to read
-    if (process.stdin.isTTY) {
-        return null;
-    }
-    return new Promise((resolve) => {
-        let data = "";
-        const timeout = setTimeout(() => {
-            process.stdin.removeAllListeners();
-            resolve(data || null);
-        }, 100); // 100ms timeout for stdin
-        process.stdin.setEncoding("utf8");
-        process.stdin.on("data", (chunk) => {
-            data += chunk;
-        });
-        process.stdin.on("end", () => {
-            clearTimeout(timeout);
-            resolve(data || null);
-        });
-        process.stdin.on("error", () => {
-            clearTimeout(timeout);
-            resolve(null);
-        });
-        process.stdin.resume();
-    });
-}
-/**
- * Parse Claude Code hook input from stdin
- */
-function parseHookInput(stdin) {
-    if (!stdin)
-        return null;
-    try {
-        return JSON.parse(stdin.trim());
-    }
-    catch {
-        return null;
-    }
-}
-// ─── Prompt Check (UserPromptSubmit Hook) ────────────────────────────────────
-/**
- * Output spec-first reminder for UserPromptSubmit hook.
- *
- * This is a simple context injection - always outputs the reminder,
- * and Claude (Opus) is smart enough to apply it when relevant.
- */
-async function sessionPromptCheckAction() {
-    // Lean, instructive reminder with kspec prefix
-    console.log(sessionPrompt.specCheck);
-}
-async function sessionCheckpointAction(options) {
-    try {
-        // Read stdin for Claude Code hook input
-        const stdin = await readStdinIfAvailable();
-        const hookInput = parseHookInput(stdin);
-        // Check if this is a retry (stop hook already active)
-        if (hookInput?.stop_hook_active) {
-            options.stopHookActive = true;
-        }
-        const ctx = await initContext();
-        const result = await performCheckpoint(ctx, options);
-        // Output format depends on mode:
-        // - JSON mode (--json): Output Claude Code hook format {"decision": "block", "reason": "..."}
-        // - Human mode: Output formatted checkpoint result
-        if (isJsonMode()) {
-            if (!result.ok) {
-                // Build reason message with issues and instructions
-                const issueLines = result.issues
-                    .map((i) => `- ${i.description}`)
-                    .join("\n");
-                const instructionLines = result.instructions
-                    .filter((i) => i.trim())
-                    .join("\n");
-                const reason = `${result.message}\n\nIssues:\n${issueLines}\n\n${instructionLines}`;
-                console.log(JSON.stringify({ decision: "block", reason }));
-            }
-            // If ok, exit silently (Claude Code expects no output when allowing stop)
-        }
-        else {
-            formatCheckpointResult(result);
-            if (!result.ok) {
-                process.exit(EXIT_CODES.ERROR);
-            }
-        }
-    }
-    catch (err) {
-        // Handle RUNNING_FROM_SHADOW gracefully - skip with warning instead of erroring
-        // This happens when the stop hook runs while cwd is inside .kspec/ directory
-        if (err instanceof ShadowError && err.code === "RUNNING_FROM_SHADOW") {
-            if (!isJsonMode()) {
-                console.log(chalk.yellow("[kspec] Session checkpoint skipped - running from inside .kspec/ directory"));
-            }
-            // Allow stop to proceed (exit successfully, no JSON output blocks the stop)
-            return;
-        }
-        error(errors.failures.runCheckpoint, err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-const VALID_SORT_FIELDS = [
-    "started_at",
-    "duration",
-    "events",
-    "iterations",
-    "tasks_completed",
-];
-/**
- * Format a duration in milliseconds to a human-readable string.
- */
-function formatDuration(ms) {
-    if (ms < 0)
-        return "—";
-    const totalSec = Math.floor(ms / 1000);
-    const hours = Math.floor(totalSec / 3600);
-    const minutes = Math.floor((totalSec % 3600) / 60);
-    if (hours > 0) {
-        return `${hours}h ${minutes}m`;
-    }
-    if (minutes > 0) {
-        return `${minutes}m`;
-    }
-    return `${totalSec}s`;
-}
-/**
- * Sort session summaries by the specified field.
- * Default: started_at descending.
- *
- * AC: @session-log-list ac-5
- */
-function sortSessions(sessions, sortField) {
-    return [...sessions].sort((a, b) => {
-        switch (sortField) {
-            case "started_at":
-                return (new Date(b.started_at).getTime() - new Date(a.started_at).getTime());
-            case "duration":
-                return b.duration_ms - a.duration_ms;
-            case "events":
-                return b.event_count - a.event_count;
-            case "iterations":
-                return b.iteration_count - a.iteration_count;
-            case "tasks_completed":
-                return b.tasks_completed - a.tasks_completed;
-            default:
-                return (new Date(b.started_at).getTime() - new Date(a.started_at).getTime());
-        }
-    });
-}
-/**
- * Format the session log list as a table.
- *
- * AC: @session-log-list ac-1
- */
-function formatSessionLogList(sessions) {
-    if (sessions.length === 0) {
-        // AC: @session-log-list ac-6
-        console.log("No sessions found.");
-        return;
-    }
-    // Table header
-    console.log(chalk.gray(`${"ID".padEnd(10)} ${"Status".padEnd(11)} ${"Agent".padEnd(20)} ${"Started".padEnd(16)} ${"Duration".padEnd(10)} ${"Events".padEnd(8)} ${"Iters".padEnd(7)} Tasks`));
-    console.log(chalk.gray("─".repeat(95)));
-    for (const s of sessions) {
-        const id = s.id.slice(0, 8);
-        const statusColor = s.status === "completed"
-            ? chalk.green
-            : s.status === "active"
-                ? chalk.blue
-                : chalk.yellow;
-        const status = statusColor(s.status.padEnd(11));
-        const agent = s.agent_type.slice(0, 20).padEnd(20);
-        const started = formatRelativeTime(new Date(s.started_at)).padEnd(16);
-        const duration = formatDuration(s.duration_ms).padEnd(10);
-        const events = String(s.event_count).padEnd(8);
-        const iters = String(s.iteration_count).padEnd(7);
-        const tasks = String(s.tasks_completed);
-        console.log(`${chalk.yellow(id)} ${status} ${chalk.gray(agent)} ${chalk.gray(started)} ${duration} ${events} ${iters} ${tasks}`);
-    }
-    console.log(chalk.gray(`\n${sessions.length} session(s)`));
-}
-/**
- * Session log list action handler.
- */
-async function sessionLogListAction(options) {
-    try {
-        const ctx = await initContext();
-        let sessions = await getAllSessionLogSummaries(ctx.specDir);
-        // AC: @session-log-list ac-2 - Filter by status
-        if (options.status) {
-            const statusFilter = options.status;
-            sessions = sessions.filter((s) => s.status === statusFilter);
-        }
-        // AC: @session-log-list ac-4 - Filter by agent type
-        if (options.agent) {
-            const agentFilter = options.agent;
-            sessions = sessions.filter((s) => s.agent_type === agentFilter);
-        }
-        // AC: @session-log-list ac-3 - Filter by since date
-        if (options.since) {
-            const sinceDate = parseTimeSpec(options.since);
-            if (sinceDate) {
-                sessions = sessions.filter((s) => new Date(s.started_at) >= sinceDate);
-            }
-        }
-        // AC: @session-log-list ac-5 - Sort
-        const sortField = options.sort && VALID_SORT_FIELDS.includes(options.sort)
-            ? options.sort
-            : "started_at";
-        sessions = sortSessions(sessions, sortField);
-        // AC: @session-log-list ac-7 - Limit output count
-        if (options.count) {
-            // AC: @trait-filterable-list ac-8
-            output({ count: sessions.length }, () => {
-                console.log(sessions.length);
-            });
-            return;
-        }
-        // Apply --limit (after filtering/sorting, before display)
-        if (options.limit) {
-            const limit = parseInt(options.limit, 10);
-            if (!Number.isNaN(limit) && limit > 0) {
-                sessions = sessions.slice(0, limit);
-            }
-        }
-        output(sessions, () => formatSessionLogList(sessions));
-    }
-    catch (err) {
-        error("Failed to list session logs", err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-/**
- * Format an event timestamp as relative time from session start.
- */
-function formatEventTimestamp(eventTs, sessionStartTs) {
-    const relativeMs = eventTs - sessionStartTs;
-    const totalSec = Math.floor(relativeMs / 1000);
-    const minutes = Math.floor(totalSec / 60);
-    const seconds = totalSec % 60;
-    if (minutes > 0) {
-        return `+${minutes}m${seconds}s`;
-    }
-    return `+${seconds}s`;
-}
-/**
- * Summarize event data for display.
- * Returns a short string describing the event payload.
- */
-function summarizeEventData(event) {
-    const data = event.data;
-    if (!data)
-        return "";
-    // Handle tool_call events
-    if (event.type === "session.update") {
-        const update = data.update;
-        if (update?.sessionUpdate === "tool_call") {
-            const toolName = update._meta?.claudeCode?.toolName || "unknown";
-            const command = update.rawInput?.command;
-            if (command) {
-                const truncated = command.length > 60 ? command.slice(0, 57) + "..." : command;
-                return `${toolName}: ${truncated}`;
-            }
-            return toolName;
-        }
-    }
-    // Handle prompt.sent events
-    if (event.type === "prompt.sent") {
-        const prompt = data.prompt;
-        if (prompt) {
-            const truncated = prompt.length > 60 ? prompt.slice(0, 57) + "..." : prompt;
-            return truncated;
-        }
-    }
-    // Handle session.start/end
-    if (event.type === "session.start") {
-        return "Session started";
-    }
-    if (event.type === "session.end") {
-        const reason = data.reason;
-        return reason ? `Session ended: ${reason}` : "Session ended";
-    }
-    // Default: show first key
-    const keys = Object.keys(data);
-    if (keys.length > 0) {
-        return `{${keys.slice(0, 3).join(", ")}${keys.length > 3 ? ", ..." : ""}}`;
-    }
-    return "";
-}
-/**
- * Format the session log show output.
- *
- * AC: @session-log-show ac-1
- */
-function formatSessionLogShow(detail, events, contextSnapshot, sessionStartTs) {
-    // AC: @session-log-show ac-1 - Session metadata
-    console.log(chalk.bold(`Session ${detail.id.slice(0, 8)}`));
-    console.log(chalk.gray("─".repeat(60)));
-    console.log(`  ID:        ${detail.id}`);
-    const statusColor = detail.status === "completed"
-        ? chalk.green
-        : detail.status === "active"
-            ? chalk.blue
-            : chalk.yellow;
-    console.log(`  Status:    ${statusColor(detail.status)}`);
-    console.log(`  Agent:     ${detail.agent_type}`);
-    if (detail.task_id) {
-        console.log(`  Task:      ${detail.task_id}`);
-    }
-    console.log(`  Started:   ${detail.started_at}`);
-    if (detail.ended_at) {
-        console.log(`  Ended:     ${detail.ended_at}`);
-    }
-    console.log(`  Duration:  ${formatDuration(detail.duration_ms)}`);
-    console.log(`  Events:    ${detail.event_count}`);
-    console.log(`  Iterations: ${detail.iteration_count}`);
-    // AC: @session-log-show ac-2 - Per-iteration summary
-    if (detail.iterations.length > 0) {
-        console.log("\n" + chalk.bold("Iterations"));
-        console.log(chalk.gray("─".repeat(60)));
-        for (const iter of detail.iterations) {
-            const taskInfo = [];
-            if (iter.tasks_started.length > 0) {
-                taskInfo.push(`started: ${iter.tasks_started.join(", ")}`);
-            }
-            if (iter.tasks_completed.length > 0) {
-                taskInfo.push(`completed: ${iter.tasks_completed.join(", ")}`);
-            }
-            const taskStr = taskInfo.length > 0 ? ` | ${taskInfo.join(" | ")}` : "";
-            console.log(`  ${chalk.cyan(`[${iter.iteration}]`)} ${iter.event_count} events${taskStr}`);
-        }
-    }
-    // AC: @session-log-show ac-3 - Event timeline
-    if (events !== null) {
-        console.log("\n" + chalk.bold("Events"));
-        console.log(chalk.gray("─".repeat(60)));
-        if (events.length === 0) {
-            console.log(chalk.gray("  No events to display."));
-        }
-        else {
-            for (const event of events) {
-                const timestamp = formatEventTimestamp(event.ts, sessionStartTs);
-                const summary = summarizeEventData(event);
-                const typeColor = event.type === "session.start" || event.type === "session.end"
-                    ? chalk.green
-                    : event.type === "session.update"
-                        ? chalk.blue
-                        : chalk.gray;
-                console.log(`  ${chalk.yellow(timestamp.padEnd(10))} ${typeColor(event.type.padEnd(16))} ${chalk.gray(summary)}`);
-            }
-        }
-    }
-    // AC: @session-log-show ac-6 - Context snapshot
-    if (contextSnapshot !== null) {
-        console.log("\n" + chalk.bold("Context Snapshot"));
-        console.log(chalk.gray("─".repeat(60)));
-        console.log(JSON.stringify(contextSnapshot, null, 2));
-    }
-}
-/**
- * Session log show action handler.
- */
-async function sessionLogShowAction(sessionRef, options) {
-    try {
-        const ctx = await initContext();
-        // AC: @session-log-show ac-7, ac-8, ac-9 - Resolve session ID
-        const resolution = await resolveSessionId(ctx.specDir, sessionRef);
-        if (!resolution.ok) {
-            if (resolution.error === "not_found") {
-                // AC: @session-log-show ac-9
-                error(`Session not found: ${sessionRef}`);
-                process.exit(EXIT_CODES.NOT_FOUND);
-            }
-            else {
-                // AC: @session-log-show ac-8
-                error(`Ambiguous session ID prefix. Matches:\n  ${resolution.matches.join("\n  ")}\nPlease provide a more specific prefix.`);
-                process.exit(EXIT_CODES.VALIDATION_FAILED);
-            }
-        }
-        const sessionId = resolution.id;
-        // Get session detail
-        const detail = await getSessionLogDetail(ctx.specDir, sessionId);
-        if (!detail) {
-            error(`Session not found: ${sessionId}`);
-            process.exit(EXIT_CODES.NOT_FOUND);
-        }
-        // AC: @session-log-show ac-3, ac-4, ac-5 - Event timeline
-        let events = null;
-        if (options.events) {
-            let allEvents = deduplicatePhasedToolCalls(await readEvents(ctx.specDir, sessionId));
-            // AC: @session-log-show ac-4 - Filter by type
-            if (options.type) {
-                const typeFilter = options.type;
-                allEvents = allEvents.filter((e) => e.type === typeFilter);
-            }
-            // AC: @session-log-show ac-5 - Limit to last N events
-            if (options.limit) {
-                const limit = parseInt(options.limit, 10);
-                if (!Number.isNaN(limit) && limit > 0) {
-                    allEvents = allEvents.slice(-limit);
-                }
-            }
-            events = allEvents;
-        }
-        // AC: @session-log-show ac-6 - Context snapshot
-        let contextSnapshot = null;
-        if (options.context) {
-            const iterNum = parseInt(options.context, 10);
-            if (!Number.isNaN(iterNum) && iterNum > 0) {
-                contextSnapshot = await readSessionContext(ctx.specDir, sessionId, iterNum);
-                if (contextSnapshot === null) {
-                    error(`No context snapshot found for iteration ${iterNum}`);
-                    process.exit(EXIT_CODES.NOT_FOUND);
-                }
-            }
-            else {
-                error(`Invalid iteration number: ${options.context}`);
-                process.exit(EXIT_CODES.USAGE_ERROR);
-            }
-        }
-        const sessionStartTs = new Date(detail.started_at).getTime();
-        // Build JSON output structure
-        const jsonOutput = {
-            ...detail,
-            ...(events !== null ? { events } : {}),
-            ...(contextSnapshot !== null ? { context: contextSnapshot } : {}),
-        };
-        output(jsonOutput, () => formatSessionLogShow(detail, events, contextSnapshot, sessionStartTs));
-    }
-    catch (err) {
-        error("Failed to show session log", err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-/**
- * Format a duration in milliseconds to human-readable format.
- * Reuses formatDuration from session log list but handles hours/minutes/seconds.
- */
-function formatDurationLong(ms) {
-    if (ms < 0)
-        return "—";
-    const totalSec = Math.floor(ms / 1000);
-    const hours = Math.floor(totalSec / 3600);
-    const minutes = Math.floor((totalSec % 3600) / 60);
-    const seconds = totalSec % 60;
-    if (hours > 0 && minutes > 0) {
-        return `${hours}h ${minutes}m`;
-    }
-    if (hours > 0) {
-        return `${hours}h`;
-    }
-    if (minutes > 0) {
-        return `${minutes}m ${seconds}s`;
-    }
-    return `${seconds}s`;
-}
-/**
- * Format the session log stats output.
- *
- * AC: @session-log-stats ac-1, ac-2, ac-3
- */
-function formatSessionLogStats(stats, toolUsage, timePeriods, groupBy) {
-    // AC: @session-log-stats ac-1 - Totals
-    console.log(chalk.bold("Session Statistics"));
-    console.log(chalk.gray("─".repeat(50)));
-    console.log(`  Total Sessions:     ${stats.total_sessions}`);
-    console.log(`  Total Events:       ${stats.total_events}`);
-    console.log(`  Total Iterations:   ${stats.total_iterations}`);
-    console.log(`  Tasks Completed:    ${stats.total_tasks_completed}`);
-    console.log(`  Total Duration:     ${formatDurationLong(stats.total_duration_ms)}`);
-    // AC: @session-log-stats ac-2 - Averages
-    console.log("\n" + chalk.bold("Averages"));
-    console.log(chalk.gray("─".repeat(50)));
-    console.log(`  Avg Duration/Session:     ${formatDurationLong(stats.avg_duration_ms)}`);
-    console.log(`  Avg Iterations/Session:   ${stats.avg_iterations_per_session}`);
-    console.log(`  Avg Tasks/Session:        ${stats.avg_tasks_per_session}`);
-    // AC: @session-log-stats ac-3 - Status breakdown
-    if (stats.status_breakdown.length > 0) {
-        console.log("\n" + chalk.bold("Status Breakdown"));
-        console.log(chalk.gray("─".repeat(50)));
-        for (const item of stats.status_breakdown) {
-            const statusColor = item.status === "completed"
-                ? chalk.green
-                : item.status === "active"
-                    ? chalk.blue
-                    : chalk.yellow;
-            console.log(`  ${statusColor(item.status.padEnd(12))} ${String(item.count).padEnd(6)} ${item.percentage}%`);
-        }
-    }
-    // AC: @session-log-stats ac-6 - Tool usage
-    if (toolUsage !== null && toolUsage.length > 0) {
-        console.log("\n" + chalk.bold("Top Tool Usage"));
-        console.log(chalk.gray("─".repeat(50)));
-        for (const tool of toolUsage) {
-            console.log(`  ${tool.tool_name.padEnd(20)} ${String(tool.count).padEnd(8)} ${tool.percentage}%`);
-        }
-    }
-    // AC: @session-log-stats ac-7 - Time periods
-    if (timePeriods !== null && timePeriods.length > 0) {
-        const label = groupBy === "week" ? "By Week" : "By Day";
-        console.log("\n" + chalk.bold(label));
-        console.log(chalk.gray("─".repeat(50)));
-        console.log(chalk.gray(`  ${"Period".padEnd(14)} ${"Sessions".padEnd(10)} ${"Tasks".padEnd(8)} Duration`));
-        for (const period of timePeriods) {
-            console.log(`  ${period.period.padEnd(14)} ${String(period.sessions_count).padEnd(10)} ${String(period.tasks_completed).padEnd(8)} ${formatDurationLong(period.total_duration_ms)}`);
-        }
-    }
-}
-/**
- * Session log stats action handler.
- */
-async function sessionLogStatsAction(options) {
-    try {
-        const ctx = await initContext();
-        let sessions = await getAllSessionLogSummaries(ctx.specDir);
-        // AC: @session-log-stats ac-4 - Filter by since
-        if (options.since) {
-            const sinceDate = parseTimeSpec(options.since);
-            if (sinceDate) {
-                sessions = sessions.filter((s) => new Date(s.started_at) >= sinceDate);
-            }
-        }
-        // AC: @session-log-stats ac-5 - Filter by agent type
-        if (options.agent) {
-            const agentFilter = options.agent;
-            sessions = sessions.filter((s) => s.agent_type === agentFilter);
-        }
-        // AC: @session-log-stats ac-8 - No sessions match criteria
-        if (sessions.length === 0) {
-            output({ message: "No sessions match criteria" }, () => {
-                console.log("No sessions match criteria.");
-            });
-            return;
-        }
-        // Compute base stats
-        const stats = computeSessionLogStats(sessions);
-        // AC: @session-log-stats ac-6 - Tool usage (optional)
-        let toolUsage = null;
-        if (options.toolUsage) {
-            const sessionIds = sessions.map((s) => s.id);
-            toolUsage = await computeToolUsageStats(ctx.specDir, sessionIds);
-        }
-        // AC: @session-log-stats ac-7 - Time periods (optional)
-        let timePeriods = null;
-        let groupBy = null;
-        if (options.byDay) {
-            groupBy = "day";
-            timePeriods = computeTimePeriodStats(sessions, "day");
-        }
-        else if (options.byWeek) {
-            groupBy = "week";
-            timePeriods = computeTimePeriodStats(sessions, "week");
-        }
-        // Build output structure
-        const jsonOutput = { stats };
-        if (toolUsage !== null) {
-            jsonOutput.tool_usage = toolUsage;
-        }
-        if (timePeriods !== null) {
-            jsonOutput.time_periods = timePeriods;
-        }
-        output(jsonOutput, () => formatSessionLogStats(stats, toolUsage, timePeriods, groupBy));
-    }
-    catch (err) {
-        error("Failed to compute session log stats", err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-/**
- * Format relative timestamp from event timestamp (Unix ms) to session start.
- */
-function formatSearchTimestamp(eventTs) {
-    return new Date(eventTs).toISOString();
-}
-/**
- * Format the session log search output.
- *
- * AC: @session-log-search ac-1, ac-4
- */
-function formatSessionLogSearch(results) {
-    if (results.length === 0) {
-        // AC: @session-log-search ac-6
-        console.log("No matches found.");
-        return;
-    }
-    let totalMatches = 0;
-    for (const session of results) {
-        totalMatches += session.matches.length;
-    }
-    console.log(chalk.bold(`Found ${totalMatches} match(es) in ${results.length} session(s)`));
-    console.log(chalk.gray("─".repeat(60)));
-    for (const session of results) {
-        // Session header
-        console.log(`\n${chalk.cyan(`Session ${session.session_id.slice(0, 8)}`)} ` +
-            `${chalk.gray(`(${session.agent_type}, started ${formatRelativeTime(new Date(session.started_at))})`)}`);
-        // AC: @session-log-search ac-4 - Show matches with session ID, timestamp, type, excerpt
-        for (const match of session.matches) {
-            const ts = formatSearchTimestamp(match.timestamp);
-            const typeColor = match.event_type === "session.start" || match.event_type === "session.end"
-                ? chalk.green
-                : match.event_type === "session.update"
-                    ? chalk.blue
-                    : chalk.gray;
-            console.log(`  ${chalk.yellow(ts)} ${typeColor(match.event_type.padEnd(16))}`);
-            // Content excerpt on next line, indented
-            console.log(`    ${chalk.gray(match.content_excerpt)}`);
-        }
-    }
-}
-/**
- * Session log search action handler.
- *
- * AC: @session-log-search ac-1 through ac-7
- */
-async function sessionLogSearchAction(pattern, options) {
-    try {
-        const ctx = await initContext();
-        // Parse options - validate limit as positive integer
-        let limit = 50;
-        if (options.limit) {
-            const parsed = parseInt(options.limit, 10);
-            if (Number.isNaN(parsed) || parsed <= 0) {
-                error(`Invalid limit: ${options.limit}. Must be a positive integer.`);
-                process.exit(EXIT_CODES.USAGE_ERROR);
-            }
-            limit = parsed;
-        }
-        const sinceDate = options.since ? parseTimeSpec(options.since) : undefined;
-        // AC: @session-log-search ac-1, ac-2, ac-3, ac-5, ac-7
-        const results = await searchSessionEvents(ctx.specDir, pattern, {
-            eventType: options.type,
-            sinceDate: sinceDate || undefined,
-            agentType: options.agent,
-            limit,
-        });
-        // AC: @session-log-search ac-6 - No matches found message
-        // exit code 0 regardless (per @trait-semantic-exit-codes ac-5)
-        output(results, () => formatSessionLogSearch(results));
-    }
-    catch (err) {
-        error("Failed to search session logs", err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-// ─── Session Create Action ─────────────────────────────────────────────────
-/**
- * Action handler for `kspec session create`.
- *
- * Creates a new session with optional budget and environment injection.
- *
- * AC: @session-creation-and-env-injection ac-create
- * AC: @session-creation-and-env-injection ac-budget
- * AC: @session-creation-and-env-injection ac-budget-local
- * AC: @session-creation-and-env-injection ac-inject-claude
- * AC: @session-creation-and-env-injection ac-inject-codex
- * AC: @session-creation-and-env-injection ac-inject-fallback
- *
- * Exit codes documented per @trait-semantic-exit-codes ac-8:
- * - 0: Session created successfully
- * - 1: Validation error (invalid budget value)
- * - 3: Runtime error (filesystem failure)
- */
-async function sessionCreateAction(options) {
-    try {
-        const ctx = await initContext();
-        // AC: @session-creation-and-env-injection ac-invalid-session
-        // Validate existing KSPEC_SESSION_ID if set — warn user if it's stale/corrupt
-        const existingSessionId = process.env.KSPEC_SESSION_ID;
-        if (existingSessionId) {
-            const validation = await validateSessionId(ctx.specDir, existingSessionId);
-            if (!validation.valid) {
-                warn(`Current KSPEC_SESSION_ID (${existingSessionId}) is invalid: ${validation.error}`);
-                info(validation.suggestion || "Creating a new session will generate a fresh ID.");
-            }
-        }
-        // Validate budget if provided
-        // AC: @trait-error-guidance ac-5 - indicate which field/value failed
-        let budgetNum;
-        if (options.budget !== undefined) {
-            // Use Number() instead of parseInt to reject "3.5", "3abc", "1e2" etc.
-            budgetNum = Number(options.budget);
-            if (isNaN(budgetNum) || budgetNum <= 0 || !Number.isInteger(budgetNum) || !/^\d+$/.test(options.budget)) {
-                // AC: @trait-error-guidance ac-2, ac-5 - include suggested action and field info
-                // AC: @trait-error-guidance ac-6 - guidance included in structured error
-                error(`Invalid budget value: "${options.budget}". Must be a positive integer.`, { suggestion: "Usage: kspec session create --budget <positive-integer>" });
-                process.exit(EXIT_CODES.USAGE_ERROR);
-            }
-        }
-        // Generate session ID
-        const sessionId = ulid();
-        // AC: @session-creation-and-env-injection ac-create, ac-budget, ac-budget-local
-        const result = await createSessionWithBudget(ctx.specDir, {
-            id: sessionId,
-            agent_type: options.agentType,
-            task_id: options.taskId,
-            budget: budgetNum,
-        });
-        // Handle environment injection if requested
-        let injection = null;
-        if (options.inject) {
-            injection = await performEnvInjection(sessionId);
-        }
-        // Build output data
-        const outputData = {
-            session_id: result.session_id,
-            agent_type: result.session.agent_type,
-            status: result.session.status,
-            started_at: result.session.started_at,
-        };
-        if (result.session.task_id) {
-            outputData.task_id = result.session.task_id;
-        }
-        if (result.budget) {
-            outputData.budget = {
-                max_per_cycle: result.budget.max_per_cycle,
-                started_this_cycle: result.budget.started_this_cycle,
-            };
-        }
-        if (injection) {
-            outputData.env_injection = {
-                method: injection.method,
-                injected: injection.injected,
-                description: injection.description,
-                ...(injection.path ? { path: injection.path } : {}),
-            };
-        }
-        // AC: @trait-json-output ac-1, ac-2, ac-5 - JSON with all data, ISO timestamps
-        output(outputData, () => {
-            // AC: @session-creation-and-env-injection ac-create - print session ID to stdout
-            success(`Created session: ${sessionId}`, { session_id: sessionId });
-            info(`Agent type: ${options.agentType}`);
-            if (result.budget) {
-                info(`Budget: ${result.budget.max_per_cycle} tasks per cycle`);
-            }
-            if (injection) {
-                if (injection.injected) {
-                    info(injection.description);
-                }
-                else {
-                    // AC: @session-creation-and-env-injection ac-inject-fallback
-                    console.log(injection.description);
-                }
-            }
-        });
-    }
-    catch (err) {
-        // AC: @trait-error-guidance ac-1 - describe what went wrong
-        // AC: @trait-json-output ac-3 - error as JSON object
-        error("Failed to create session", err);
-        process.exit(EXIT_CODES.ERROR);
-    }
-}
-/**
- * Detect agent harness and perform environment injection.
- *
- * AC: @session-creation-and-env-injection ac-inject-claude
- * AC: @session-creation-and-env-injection ac-inject-codex
- * AC: @session-creation-and-env-injection ac-inject-fallback
- */
-async function performEnvInjection(sessionId) {
-    // Detect Claude Code
-    if (process.env.CLAUDECODE === "1" ||
-        process.env.CLAUDE_CODE_ENTRYPOINT ||
-        process.env.CLAUDE_PROJECT_DIR) {
-        return injectClaudeCodeEnv(sessionId);
-    }
-    // Detect Codex CLI
-    if (process.env.CODEX_SANDBOX) {
-        return injectCodexEnv(sessionId);
-    }
-    // Detect Gemini CLI
-    if (process.env.GEMINI_CLI === "1") {
-        return injectGeminiEnv(sessionId);
-    }
-    // Detect OpenCode
-    if (process.env.OPENCODE_CONFIG_DIR || process.env.OPENCODE_CONFIG) {
-        return injectOpenCodeEnv(sessionId);
-    }
-    // Fallback for unknown harnesses
-    return getFallbackInjectionInstructions(sessionId);
-}
-/**
- * Register the 'session' command group and aliases
- */
-export function registerSessionCommands(program) {
-    const session = program
-        .command("session")
-        .description("Session management and context");
-    // Session create subcommand
-    markMutating(session.command("create"))
-        .description("Create a new kspec session with optional budget")
-        .option("--agent-type <type>", "Agent type (e.g., claude-code, codex-cli)", "claude-code")
-        .option("--budget <n>", "Maximum tasks per cycle (positive integer)")
-        .option("--inject", "Inject KSPEC_SESSION_ID into agent environment")
-        .option("--task-id <id>", "Optional task ID being worked on")
-        .action(sessionCreateAction);
-    session
-        .command("start")
-        .alias("resume")
-        .description("Surface relevant context for starting a new working session")
-        .option("--brief", "Compact summary (default)")
-        .option("--full", "Comprehensive context dump")
-        .option("--since <time>", "Filter by recency (ISO8601 or relative: 1h, 2d, 1w)")
-        .option("--no-git", "Skip git commit information")
-        .option("-n, --limit <n>", "Limit items per section", "10")
-        .action(sessionStartAction);
-    // Session log subcommand group
-    const log = session
-        .command("log")
-        .description("Session log analysis commands");
-    log
-        .command("list")
-        .description("List session logs with summary statistics")
-        .option("-s, --status <status>", "Filter by status (active, completed, abandoned)")
-        .option("--agent <type>", "Filter by agent type")
-        .option("--since <time>", "Only show sessions started after this time (ISO8601 or relative: 1h, 2d, 1w)")
-        .option("--sort <field>", "Sort by field (started_at, duration, events, iterations, tasks_completed)", "started_at")
-        .option("--count", "Show only the count of matching sessions")
-        .option("-n, --limit <n>", "Limit number of sessions shown")
-        .action(sessionLogListAction);
-    log
-        .command("show <session-id>")
-        .description("Show detailed view of a single session")
-        .option("-e, --events", "Include chronological event timeline")
-        .option("-t, --type <type>", "Filter events by type (e.g., tool.call)")
-        .option("-n, --limit <n>", "Show only the last N events")
-        .option("-c, --context <n>", "Show context snapshot for iteration N")
-        .action(sessionLogShowAction);
-    log
-        .command("stats")
-        .description("Aggregate analytics across sessions")
-        .option("--since <time>", "Only include sessions started after this time (ISO8601 or relative: 1h, 2d, 1w)")
-        .option("--agent <type>", "Only include sessions with this agent type")
-        .option("--tool-usage", "Display top 10 tool calls by frequency")
-        .option("--by-day", "Group stats by day")
-        .option("--by-week", "Group stats by week")
-        .action(sessionLogStatsAction);
-    log
-        .command("search <pattern>")
-        .description("Search across session events by content")
-        .option("-t, --type <type>", "Only search events of this type (e.g., session.update)")
-        .option("--since <time>", "Only search sessions started after this time (ISO8601 or relative: 1h, 2d, 1w)")
-        .option("--agent <type>", "Only search sessions with this agent type")
-        .option("-n, --limit <n>", "Maximum matches to return (default: 50)")
-        .action(sessionLogSearchAction);
-    session
-        .command("checkpoint")
-        .description("Pre-stop hook: check for uncommitted work before ending session")
-        .option("--force", "Allow session end regardless of issues")
-        .action(sessionCheckpointAction);
-    session
-        .command("prompt-check")
-        .description("UserPromptSubmit hook: inject spec-first reminder")
-        .action(sessionPromptCheckAction);
-    // Top-level alias: kspec context
-    program
-        .command("context")
-        .description("Alias for session start - surface session context")
-        .option("--brief", "Compact summary (default)")
-        .option("--full", "Comprehensive context dump")
-        .option("--since <time>", "Filter by recency (ISO8601 or relative: 1h, 2d, 1w)")
-        .option("--no-git", "Skip git commit information")
-        .option("-n, --limit <n>", "Limit items per section", "10")
-        .action(sessionStartAction);
-}
+export { 
+// Functions
+gatherSessionContext, getIterationStats, performCheckpoint, getDisplayRef, formatPriority, statusColor, registerSessionCommands, } from "./session/index.js";
 //# sourceMappingURL=session.js.map