@kynetic-ai/spec 0.3.0 → 0.5.0

package/dist/cli/commands/session.js

@@ -4,20 +4,46 @@
  * Provides context for starting/resuming work sessions.
  */
 import chalk from "chalk";
-import { getReadyTasks, initContext, loadAllItems, loadAllTasks, loadInboxItems, loadSessionContext, ReferenceIndex, } from "../../parser/index.js";
+import { getReadyTasks, initContext, loadAllItems, loadAllTasks, loadInboxItems, loadSessionContext, loadTriageRecords, ReferenceIndex, } from "../../parser/index.js";
 import { ShadowError, shadowPull, } from "../../parser/shadow.js";
-import { getAllSessionLogSummaries, getSessionLogDetail, resolveSessionId, readEvents, readSessionContext, computeSessionLogStats, computeToolUsageStats, computeTimePeriodStats, searchSessionEvents, } from "../../sessions/store.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, isJsonMode, isNoteSuperseded, output } from "../output.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,
@@ -27,16 +53,19 @@ function toActiveTaskSummary(task, index) {
         incomplete_todos: incompleteTodos,
     };
 }
-function toReadyTaskSummary(task, index) {
+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) {
+function toBlockedTaskSummary(task, _allTasks, index, unlocksMap) {
     // Find unmet dependencies
     const unmetDeps = [];
     for (const depRef of task.depends_on) {
@@ -50,14 +79,18 @@ function toBlockedTaskSummary(task, _allTasks, index) {
     }
     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,
@@ -120,6 +153,80 @@ function collectIncompleteTodos(tasks, index, options) {
         .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
  */
@@ -131,7 +238,14 @@ export async function gatherSessionContext(ctx, options) {
     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,
@@ -178,16 +292,21 @@ export async function gatherSessionContext(ctx, options) {
         .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 });
-    // Get ready tasks (optionally filtered to automation-eligible only)
+    // 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, options.full ? undefined : limit)
-        .map((t) => toReadyTaskSummary(t, index));
+        .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));
+        .map((t) => toBlockedTaskSummary(t, allTasks, index, unlocksMap));
     // Get recently completed tasks
     const recentlyCompleted = allTasks
         .filter((t) => {
@@ -223,22 +342,93 @@ export async function gatherSessionContext(ctx, options) {
             date: c.date.toISOString(),
             message: c.message,
             author: c.author,
+            task_refs: c.taskRefs,
         }));
         workingTree = getWorkingTreeStatus(ctx.rootDir);
     }
-    // Get inbox items (oldest first to encourage triage)
-    const inboxSummaries = inboxItems
+    // 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())
-        .slice(0, options.full ? undefined : limit)
-        .map((item) => ({
-        ref: item._ulid.slice(0, 8),
-        text: item.text,
-        created_at: item.created_at,
-        tags: item.tags,
-        added_by: item.added_by || null,
-    }));
+        .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,
@@ -251,9 +441,13 @@ export async function gatherSessionContext(ctx, options) {
         blocked_tasks: blockedTasks,
         recently_completed: recentlyCompleted,
         recent_commits: recentCommits,
+        activity_timeline: activityTimeline,
         working_tree: workingTree,
         inbox_items: inboxSummaries,
+        inbox_stats: inboxStats,
+        observations,
         stats,
+        computed,
     };
 }
 /**
@@ -262,10 +456,17 @@ export async function gatherSessionContext(ctx, options) {
  */
 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 false;
-        return new Date(t.completed_at) >= since;
+        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)
@@ -427,7 +628,10 @@ function formatCheckpointResult(result) {
     }
 }
 function formatSessionContext(ctx, options) {
-    const isBrief = !options.full;
+    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));
@@ -466,9 +670,15 @@ function formatSessionContext(ctx, options) {
             }
         }
     }
-    // Active tasks section
+    // ── 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))})`)
@@ -476,106 +686,88 @@ function formatSessionContext(ctx, options) {
             const priority = task.priority <= 2
                 ? chalk.red(`P${task.priority}`)
                 : chalk.gray(`P${task.priority}`);
-            console.log(`  ${chalk.blue("[in_progress]")} ${priority} ${task.ref} ${task.title}${started}`);
+            // 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)`));
+                }
+            }
         }
     }
-    else {
-        console.log(`\n${sessionHeaders.noActiveWork}`);
-    }
-    // Awaiting review section
+    // ── 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} ${task.ref} ${task.title}`);
-        }
-    }
-    // Recently completed section
-    if (ctx.recently_completed.length > 0) {
-        console.log(`\n${sessionHeaders.recentlyCompleted}`);
-        const observationPromotedTasks = [];
-        for (const task of ctx.recently_completed) {
-            const completedAge = formatRelativeTime(new Date(task.completed_at));
-            let reason = "";
-            if (task.closed_reason) {
-                const maxLen = isBrief ? 60 : 120;
-                const truncated = task.closed_reason.length > maxLen
-                    ? `${task.closed_reason.slice(0, maxLen).trim()}...`
-                    : task.closed_reason;
-                reason = chalk.gray(` - ${truncated}`);
-            }
-            console.log(`  ${chalk.green("[completed]")} ${task.ref} ${task.title} ${chalk.gray(`(${completedAge})`)}${reason}`);
-            // Track tasks that came from observations
-            if (task.origin === "observation_promotion") {
-                observationPromotedTasks.push(task.ref);
+            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)`));
+                }
             }
         }
-        // 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`));
-        }
     }
-    // Recent notes section - grouped by task status
-    // AC: @cmd-session-start ac-1, ac-2
-    if (ctx.recent_notes.length > 0) {
-        console.log(`\n${sessionHeaders.recentNotes}`);
-        // Group notes by task status
-        const inProgressNotes = ctx.recent_notes.filter((n) => n.task_status === "in_progress");
-        const pendingReviewNotes = ctx.recent_notes.filter((n) => n.task_status === "pending_review");
-        const completedNotes = ctx.recent_notes.filter((n) => n.task_status === "completed");
-        // Helper to format a single note
-        const formatNote = (note) => {
-            const age = formatRelativeTime(new Date(note.created_at));
-            const author = note.author ? chalk.gray(` by ${note.author}`) : "";
-            console.log(`    ${chalk.yellow(age)} on ${note.task_ref}${author}:`);
-            // Truncate content in brief mode
-            let content = note.content.trim();
-            if (isBrief && content.length > 200) {
-                content = `${content.slice(0, 200).trim()}...`;
-            }
-            // Indent content, limit lines in brief mode
-            const lines = content.split("\n");
-            const maxLines = isBrief ? 3 : lines.length;
-            for (const line of lines.slice(0, maxLines)) {
-                console.log(`      ${chalk.white(line)}`);
-            }
-            if (isBrief && lines.length > maxLines) {
-                console.log(chalk.gray(`      ... (${lines.length - maxLines} more lines)`));
-            }
-        };
-        // AC: @cmd-session-start ac-1 - In Progress notes
-        if (inProgressNotes.length > 0) {
-            console.log(`  ${chalk.blue("In Progress:")}`);
-            for (const note of inProgressNotes) {
-                formatNote(note);
-            }
-        }
-        // AC: @cmd-session-start ac-1 - Pending Review notes (grouped separately)
-        if (pendingReviewNotes.length > 0) {
-            console.log(`  ${chalk.yellow("Pending Review:")}`);
-            for (const note of pendingReviewNotes) {
-                formatNote(note);
+    // ── 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(", ")}`));
             }
-        }
-        // AC: @cmd-session-start ac-2 - Recently Completed notes
-        if (completedNotes.length > 0) {
-            console.log(`  ${chalk.green("Recently Completed:")}`);
-            for (const note of completedNotes) {
-                formatNote(note);
+            if (task.unmet_deps.length > 0) {
+                console.log(chalk.gray(`    Waiting on: ${task.unmet_deps.join(", ")}`));
             }
         }
     }
-    // Incomplete todos section
-    if (ctx.active_todos.length > 0) {
-        console.log(`\n${sessionHeaders.incompleteTodos}`);
-        for (const todo of ctx.active_todos) {
-            console.log(`  ${chalk.yellow("[ ]")} ${todo.task_ref}#${todo.id}: ${todo.text}`);
-        }
-    }
-    // Ready tasks section
+    // ── Ready tasks section ──
     if (ctx.ready_tasks.length > 0) {
         console.log(`\n${sessionHeaders.readyTasks}`);
         for (const task of ctx.ready_tasks) {
@@ -583,48 +775,159 @@ function formatSessionContext(ctx, options) {
                 ? chalk.red(`P${task.priority}`)
                 : chalk.gray(`P${task.priority}`);
             const tags = task.tags.length > 0 ? chalk.cyan(` #${task.tags.join(" #")}`) : "";
-            console.log(`  ${priority} ${task.ref} ${task.title}${tags}`);
+            const unlocks = task.unlocks > 0 ? chalk.green(` unlocks ${task.unlocks}`) : "";
+            console.log(`  ${priority} ${displayRef(task)} ${task.title}${unlocks}${tags}`);
         }
     }
-    // Blocked tasks section
-    if (ctx.blocked_tasks.length > 0) {
-        console.log(`\n${sessionHeaders.blocked}`);
-        for (const task of ctx.blocked_tasks) {
-            console.log(`  ${chalk.red("[blocked]")} ${task.ref} ${task.title}`);
-            if (task.blocked_by.length > 0) {
-                console.log(chalk.gray(`    Blockers: ${task.blocked_by.join(", ")}`));
+    // ── 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;
+                }
             }
-            if (task.unmet_deps.length > 0) {
-                console.log(chalk.gray(`    Waiting on: ${task.unmet_deps.join(", ")}`));
+            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 });
             }
         }
-    }
-    // Git commits section
-    if (ctx.recent_commits.length > 0) {
-        console.log(`\n${sessionHeaders.recentCommits}`);
-        for (const commit of ctx.recent_commits) {
-            const age = formatRelativeTime(new Date(commit.date));
-            console.log(`  ${chalk.yellow(commit.hash)} ${commit.message} ${chalk.gray(`(${age}, ${commit.author})`)}`);
+        // 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 (oldest first to encourage triage)
-    if (ctx.inbox_items.length > 0) {
+    // ── 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}`);
-        for (const item of ctx.inbox_items) {
-            const age = 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(", ")}]`) : "";
-            // Truncate text in brief mode
-            let text = item.text;
-            if (isBrief && text.length > 60) {
-                text = `${text.slice(0, 60).trim()}...`;
+        // 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}`);
             }
-            console.log(`  ${chalk.magenta(item.ref)} ${chalk.gray(`(${age}${author})`)}${tags}`);
-            console.log(`    ${text}`);
         }
-        console.log(`  ${hints.inboxPromote}`);
+        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
+    // ── 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) {
@@ -641,32 +944,30 @@ function formatSessionContext(ctx, options) {
         }
         if (ctx.working_tree.untracked.length > 0) {
             console.log(chalk.gray("  Untracked:"));
-            const limit = isBrief ? 5 : ctx.working_tree.untracked.length;
-            for (const path of ctx.working_tree.untracked.slice(0, limit)) {
-                console.log(`    ${chalk.gray("?")} ${path}`);
+            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 (isBrief && ctx.working_tree.untracked.length > limit) {
-                console.log(chalk.gray(`    ... and ${ctx.working_tree.untracked.length - limit} more`));
+            if (!isFull && ctx.working_tree.untracked.length > untrackedLimit) {
+                console.log(chalk.gray(`    ... and ${ctx.working_tree.untracked.length - untrackedLimit} more`));
             }
         }
     }
-    else if (ctx.working_tree?.clean) {
-        console.log(`\n${sessionHeaders.workingTreeClean}`);
-    }
-    // Quick Commands section - contextual hints based on state
+    // ── Quick Commands section ──
     const quickCommands = [];
     if (ctx.active_tasks.length > 0) {
-        const ref = ctx.active_tasks[0].ref;
-        quickCommands.push(`kspec task note @${ref} "Progress..."  ${chalk.gray("# document work")}`);
-        quickCommands.push(`kspec task complete @${ref} --reason "..."  ${chalk.gray("# finish task")}`);
+        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 = ctx.ready_tasks[0].ref;
-        quickCommands.push(`kspec task start @${ref}  ${chalk.gray("# begin work")}`);
+        const ref = displayRef(ctx.ready_tasks[0]);
+        quickCommands.push(`kspec task start ${ref}  ${chalk.gray("# begin work")}`);
     }
-    if (ctx.inbox_items.length > 0) {
-        const ref = ctx.inbox_items[0].ref;
-        quickCommands.push(`kspec inbox promote @${ref} --title "..."  ${chalk.gray("# convert to task")}`);
+    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")}`);
@@ -689,12 +990,11 @@ async function sessionStartAction(options) {
             syncResult = await shadowPull(ctx.shadow.worktreeDir);
             // AC: @shadow-sync ac-3 - Warn about conflicts but continue with local state
             if (syncResult.hadConflict) {
-                console.log(chalk.yellow("⚠ Shadow sync conflict detected. Run `kspec shadow resolve` to fix."));
-                console.log(chalk.gray("  Continuing with local state..."));
-                console.log("");
+                warn("Shadow sync conflict detected. Run `kspec shadow resolve` to fix.");
+                info("Continuing with local state...");
             }
             else if (syncResult.pulled) {
-                console.log(chalk.gray("ℹ Synced shadow branch from remote"));
+                info("Synced shadow branch from remote");
             }
         }
         const sessionCtx = await gatherSessionContext(ctx, options);
@@ -1095,7 +1395,7 @@ async function sessionLogShowAction(sessionRef, options) {
         // AC: @session-log-show ac-3, ac-4, ac-5 - Event timeline
         let events = null;
         if (options.events) {
-            let allEvents = await readEvents(ctx.specDir, sessionId);
+            let allEvents = deduplicatePhasedToolCalls(await readEvents(ctx.specDir, sessionId));
             // AC: @session-log-show ac-4 - Filter by type
             if (options.type) {
                 const typeFilter = options.type;
@@ -1350,6 +1650,143 @@ async function sessionLogSearchAction(pattern, options) {
         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
  */
@@ -1357,6 +1794,14 @@ 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")