@kynetic-ai/spec 0.10.0 → 0.12.0

package/dist/sessions/store.js

@@ -7,7 +7,7 @@
  * - Session metadata management
  *
  * Storage structure:
- *   .kspec/sessions/{session-id}/
+ *   .kspec-sessions/{session-id}/
  *     session.yaml      # Metadata
  *     events.jsonl      # Append-only event log
  */
@@ -17,10 +17,9 @@ import * as path from "node:path";
 import { createHash, randomUUID } from "node:crypto";
 import { parse as parseTOML, stringify as stringifyTOML } from "smol-toml";
 import * as YAML from "yaml";
-import { shadowAutoCommit } from "../parser/shadow.js";
 import { SessionEventSchema, SessionMetadataSchema, TaskBudgetSchema, } from "./types.js";
+import { sessionBranchAutoCommit, } from "../parser/session-branch.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
-const SESSIONS_DIR = "sessions";
 const METADATA_FILE = "session.yaml";
 const EVENTS_FILE = "events.jsonl";
 const BUDGET_FILE = "budget.json";
@@ -31,64 +30,104 @@ const EVENT_LINE_MAX_BYTES = 256 * 1024;
 const EVENT_FIELD_EXTERNALIZE_BYTES = 16 * 1024;
 const EVENT_PREVIEW_MAX_BYTES = 512;
 const EVENT_SEQ_TAIL_READ_BYTES = EVENT_LINE_MAX_BYTES + 1024;
+// ─── Session Branch Auto-Commit ──────────────────────────────────────────────
+// AC: @session-branch-worktree ac-commit-boundaries
+// When sessionsDir is a git worktree (sessions.storage=branch), auto-commit at
+// lifecycle boundaries (create, close, stale cleanup, compact).
+// Event appends are NOT committed individually.
+/**
+ * Check if sessionsDir is a git worktree (has a .git file, not directory).
+ * Cached per path to avoid repeated filesystem checks.
+ */
+const worktreeCache = new Map();
+async function isSessionWorktree(sessionsDir) {
+    const cached = worktreeCache.get(sessionsDir);
+    if (cached !== undefined)
+        return cached;
+    try {
+        const gitPath = path.join(sessionsDir, ".git");
+        const stat = await fsPromises.stat(gitPath);
+        // Worktrees have a .git FILE pointing to the main repo
+        const isWorktree = stat.isFile();
+        worktreeCache.set(sessionsDir, isWorktree);
+        return isWorktree;
+    }
+    catch {
+        worktreeCache.set(sessionsDir, false);
+        return false;
+    }
+}
+/**
+ * Auto-commit to session branch at lifecycle boundaries.
+ * No-op if sessionsDir is not a git worktree.
+ */
+async function commitAtLifecycleBoundary(sessionsDir, message) {
+    if (await isSessionWorktree(sessionsDir)) {
+        await sessionBranchAutoCommit(sessionsDir, message);
+    }
+}
 // ─── Path Helpers ────────────────────────────────────────────────────────────
+// AC: @session-storage-path-resolution ac-resolver ac-path-helpers
+// All path helpers accept sessionsDir (.kspec-sessions/ at project root),
+// not sessionsDir (.kspec/). This decouples session storage from the shadow branch.
 /**
- * Get the sessions directory path within a spec directory.
+ * Get the sessions root directory.
+ * @deprecated Use ctx.sessionsDir directly. Kept for backward compatibility.
  */
-export function getSessionsDir(specDir) {
-    return path.join(specDir, SESSIONS_DIR);
+export function getSessionsDir(sessionsDir) {
+    return sessionsDir;
 }
 /**
  * Get the path to a specific session's directory.
  */
-export function getSessionDir(specDir, sessionId) {
-    return path.join(getSessionsDir(specDir), sessionId);
+export function getSessionDir(sessionsDir, sessionId) {
+    return path.join(sessionsDir, sessionId);
 }
 /**
  * Get the path to a session's metadata file.
  */
-export function getSessionMetadataPath(specDir, sessionId) {
-    return path.join(getSessionDir(specDir, sessionId), METADATA_FILE);
+export function getSessionMetadataPath(sessionsDir, sessionId) {
+    return path.join(getSessionDir(sessionsDir, sessionId), METADATA_FILE);
 }
 /**
  * Get the path to a session's events file.
  */
-export function getSessionEventsPath(specDir, sessionId) {
-    return path.join(getSessionDir(specDir, sessionId), EVENTS_FILE);
+export function getSessionEventsPath(sessionsDir, sessionId) {
+    return path.join(getSessionDir(sessionsDir, sessionId), EVENTS_FILE);
 }
 /**
  * Get the path to a session's context snapshot file for a given iteration.
  */
-export function getSessionContextPath(specDir, sessionId, iteration) {
-    return path.join(getSessionDir(specDir, sessionId), `context-iter-${iteration}.json`);
+export function getSessionContextPath(sessionsDir, sessionId, iteration) {
+    return path.join(getSessionDir(sessionsDir, sessionId), `context-iter-${iteration}.json`);
 }
 /**
  * Get the path to a session's budget file.
  * AC: @session-creation-and-env-injection ac-budget-local
  */
-export function getSessionBudgetPath(specDir, sessionId) {
-    return path.join(getSessionDir(specDir, sessionId), BUDGET_FILE);
+export function getSessionBudgetPath(sessionsDir, sessionId) {
+    return path.join(getSessionDir(sessionsDir, sessionId), BUDGET_FILE);
 }
 /**
  * Get the path to a session's blob directory.
  */
-export function getSessionBlobDir(specDir, sessionId) {
-    return path.join(getSessionDir(specDir, sessionId), BLOBS_DIR);
+export function getSessionBlobDir(sessionsDir, sessionId) {
+    return path.join(getSessionDir(sessionsDir, sessionId), BLOBS_DIR);
 }
 // ─── Session CRUD ────────────────────────────────────────────────────────────
 /**
  * Create a new session with metadata.
  *
- * AC-1: Creates .kspec/sessions/{id}/ directory with session.yaml metadata file.
+ * AC-1: Creates .kspec-sessions/{id}/ directory with session.yaml metadata file.
  * AC-5: Metadata includes task_id (optional), agent_type, status, started_at, ended_at.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param input - Session metadata input
  * @returns The created session metadata
  */
-export async function createSession(specDir, input) {
-    const sessionDir = getSessionDir(specDir, input.id);
-    const metadataPath = getSessionMetadataPath(specDir, input.id);
+export async function createSession(sessionsDir, input) {
+    const sessionDir = getSessionDir(sessionsDir, input.id);
+    const metadataPath = getSessionMetadataPath(sessionsDir, input.id);
     // Create session directory
     await fsPromises.mkdir(sessionDir, { recursive: true });
     // Build full metadata
@@ -111,17 +150,19 @@ export async function createSession(specDir, input) {
         sortMapEntries: false,
     });
     await fsPromises.writeFile(metadataPath, content, "utf-8");
+    // AC: @session-branch-worktree ac-commit-boundaries — commit on session create
+    await commitAtLifecycleBoundary(sessionsDir, `session: create (${input.id})`);
     return validated;
 }
 /**
  * Read session metadata.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Session metadata or null if not found
  */
-export async function getSession(specDir, sessionId) {
-    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+export async function getSession(sessionsDir, sessionId) {
+    const metadataPath = getSessionMetadataPath(sessionsDir, sessionId);
     try {
         const content = await fsPromises.readFile(metadataPath, "utf-8");
         const raw = YAML.parse(content);
@@ -142,13 +183,13 @@ export async function getSession(specDir, sessionId) {
  *
  * AC-6: Updates metadata with status and ended_at timestamp when session ends.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param status - New status
  * @returns Updated metadata or null if session not found
  */
-export async function updateSessionStatus(specDir, sessionId, status) {
-    const metadata = await getSession(specDir, sessionId);
+export async function updateSessionStatus(sessionsDir, sessionId, status) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata) {
         return null;
     }
@@ -158,7 +199,7 @@ export async function updateSessionStatus(specDir, sessionId, status) {
         status,
         ended_at: status !== "active" ? new Date().toISOString() : metadata.ended_at,
     };
-    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const metadataPath = getSessionMetadataPath(sessionsDir, sessionId);
     const content = YAML.stringify(updated, {
         indent: 2,
         lineWidth: 100,
@@ -170,11 +211,10 @@ export async function updateSessionStatus(specDir, sessionId, status) {
 /**
  * List all sessions.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @returns Array of session IDs
  */
-export async function listSessions(specDir) {
-    const sessionsDir = getSessionsDir(specDir);
+export async function listSessions(sessionsDir) {
     try {
         const entries = await fsPromises.readdir(sessionsDir, {
             withFileTypes: true,
@@ -185,11 +225,35 @@ export async function listSessions(specDir) {
         return [];
     }
 }
+/**
+ * Count completed sessions grouped by agent_id.
+ *
+ * Reads only session metadata (not events.jsonl) for performance.
+ * A session counts as "completed" if its status is "completed".
+ *
+ * @param sessionsDir - The .kspec directory path
+ * @returns Map of agent_id to completed session count
+ */
+export async function getCompletedSessionCountsByAgent(sessionsDir) {
+    const sessionIds = await listSessions(sessionsDir);
+    const counts = {};
+    // Read metadata in parallel for performance
+    const metadataResults = await Promise.all(sessionIds.map((id) => getSession(sessionsDir, id)));
+    for (const metadata of metadataResults) {
+        if (!metadata)
+            continue;
+        if (metadata.status !== "completed")
+            continue;
+        const agentId = metadata.agent_id ?? metadata.agent_type;
+        counts[agentId] = (counts[agentId] || 0) + 1;
+    }
+    return counts;
+}
 /**
  * Check if a session exists.
  */
-export async function sessionExists(specDir, sessionId) {
-    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+export async function sessionExists(sessionsDir, sessionId) {
+    const metadataPath = getSessionMetadataPath(sessionsDir, sessionId);
     try {
         await fsPromises.access(metadataPath);
         return true;
@@ -207,13 +271,13 @@ export async function sessionExists(specDir, sessionId) {
  *
  * AC: @session-end-loop-signal ac-signal
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param reason - Optional reason for ending the loop
  * @returns Updated metadata or null if session not found
  */
-export async function requestEndLoop(specDir, sessionId, reason) {
-    const metadata = await getSession(specDir, sessionId);
+export async function requestEndLoop(sessionsDir, sessionId, reason) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata) {
         return null;
     }
@@ -222,7 +286,7 @@ export async function requestEndLoop(specDir, sessionId, reason) {
         end_requested: true,
         end_reason: reason,
     };
-    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const metadataPath = getSessionMetadataPath(sessionsDir, sessionId);
     const content = YAML.stringify(updated, {
         indent: 2,
         lineWidth: 100,
@@ -240,12 +304,12 @@ export async function requestEndLoop(specDir, sessionId, reason) {
  *
  * AC: @session-end-loop-signal ac-detect
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Object with requested flag and optional reason, or null if session not found
  */
-export async function isEndLoopRequested(specDir, sessionId) {
-    const metadata = await getSession(specDir, sessionId);
+export async function isEndLoopRequested(sessionsDir, sessionId) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata) {
         return null;
     }
@@ -263,30 +327,42 @@ export async function isEndLoopRequested(specDir, sessionId) {
  * AC: @session-end-loop-signal ac-session-close-signal
  * AC: @session-end-loop-signal ac-session-close-error
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param status - New status (completed or abandoned)
  * @param reason - Reason for closing
  * @returns Updated metadata or null if session not found
  */
-export async function closeSession(specDir, sessionId, status, reason) {
-    const metadata = await getSession(specDir, sessionId);
+export async function closeSession(sessionsDir, sessionId, status, reason) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata) {
         return null;
     }
+    // AC: @session-summary-cache ac-persist-on-close — compute stats from events.jsonl
+    // and persist in session metadata so list endpoints never need to scan event data.
+    const [eventCount, iterationCount, tasksCompleted] = await Promise.all([
+        countEventLines(sessionsDir, sessionId),
+        countIterations(sessionsDir, sessionId),
+        countTaskCompletions(sessionsDir, sessionId),
+    ]);
     const updated = {
         ...metadata,
         status,
         ended_at: new Date().toISOString(),
         close_reason: reason,
+        event_count: eventCount,
+        iteration_count: iterationCount,
+        tasks_completed: tasksCompleted,
     };
-    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const metadataPath = getSessionMetadataPath(sessionsDir, sessionId);
     const content = YAML.stringify(updated, {
         indent: 2,
         lineWidth: 100,
         sortMapEntries: false,
     });
     await fsPromises.writeFile(metadataPath, content, "utf-8");
+    // AC: @session-branch-worktree ac-commit-boundaries — commit on session close
+    await commitAtLifecycleBoundary(sessionsDir, `session: close ${status} (${sessionId})`);
     return updated;
 }
 function isRecord(value) {
@@ -360,7 +436,7 @@ function shouldExternalizeField(pathSegments, value) {
     }
     return false;
 }
-async function createBlobPointer(specDir, sessionId, seq, pathSegments, value, context) {
+async function createBlobPointer(sessionsDir, sessionId, seq, pathSegments, value, context) {
     const content = stringifyPayload(value);
     const bytes = Buffer.byteLength(content, "utf-8");
     const sha256 = createHash("sha256").update(content).digest("hex");
@@ -375,7 +451,7 @@ async function createBlobPointer(specDir, sessionId, seq, pathSegments, value, c
             await fsPromises.mkdir(context.blobDir, { recursive: true });
             context.ensuredDir = true;
         }
-        const absolutePath = path.join(getSessionDir(specDir, sessionId), relativePath);
+        const absolutePath = path.join(getSessionDir(sessionsDir, sessionId), relativePath);
         await fsPromises.writeFile(absolutePath, content, "utf-8");
     }
     context.createdBlobs = (context.createdBlobs ?? 0) + 1;
@@ -388,15 +464,15 @@ async function createBlobPointer(specDir, sessionId, seq, pathSegments, value, c
         preview: toPreview(content),
     };
 }
-async function externalizeOversizedPayloads(specDir, sessionId, seq, value, pathSegments, context) {
+async function externalizeOversizedPayloads(sessionsDir, sessionId, seq, value, pathSegments, context) {
     if (isSessionBlobPointer(value)) {
         return value;
     }
     if (shouldExternalizeField(pathSegments, value)) {
-        return createBlobPointer(specDir, sessionId, seq, pathSegments, value, context);
+        return createBlobPointer(sessionsDir, sessionId, seq, pathSegments, value, context);
     }
     if (Array.isArray(value)) {
-        return Promise.all(value.map((entry, idx) => externalizeOversizedPayloads(specDir, sessionId, seq, entry, [
+        return Promise.all(value.map((entry, idx) => externalizeOversizedPayloads(sessionsDir, sessionId, seq, entry, [
             ...pathSegments,
             String(idx),
         ], context)));
@@ -404,14 +480,14 @@ async function externalizeOversizedPayloads(specDir, sessionId, seq, value, path
     if (isRecord(value)) {
         const next = {};
         for (const [key, child] of Object.entries(value)) {
-            next[key] = await externalizeOversizedPayloads(specDir, sessionId, seq, child, [...pathSegments, key], context);
+            next[key] = await externalizeOversizedPayloads(sessionsDir, sessionId, seq, child, [...pathSegments, key], context);
         }
         return next;
     }
     return value;
 }
-function resolveBlobAbsolutePath(specDir, sessionId, relativePath) {
-    const sessionDir = path.resolve(getSessionDir(specDir, sessionId));
+function resolveBlobAbsolutePath(sessionsDir, sessionId, relativePath) {
+    const sessionDir = path.resolve(getSessionDir(sessionsDir, sessionId));
     const absolutePath = path.resolve(sessionDir, relativePath);
     if (absolutePath === sessionDir ||
         absolutePath.startsWith(`${sessionDir}${path.sep}`)) {
@@ -419,8 +495,8 @@ function resolveBlobAbsolutePath(specDir, sessionId, relativePath) {
     }
     return null;
 }
-async function resolveBlobPointer(specDir, sessionId, pointer) {
-    const absolutePath = resolveBlobAbsolutePath(specDir, sessionId, pointer.path);
+async function resolveBlobPointer(sessionsDir, sessionId, pointer) {
+    const absolutePath = resolveBlobAbsolutePath(sessionsDir, sessionId, pointer.path);
     if (!absolutePath) {
         return { ...pointer, content: pointer.preview };
     }
@@ -438,17 +514,17 @@ async function resolveBlobPointer(specDir, sessionId, pointer) {
  * Default flows keep compact pointer objects (preview-only). This helper powers
  * explicit on-demand blob resolution in session log commands.
  */
-export async function resolveSessionBlobPointers(specDir, sessionId, value) {
+export async function resolveSessionBlobPointers(sessionsDir, sessionId, value) {
     if (isSessionBlobPointer(value)) {
-        return resolveBlobPointer(specDir, sessionId, value);
+        return resolveBlobPointer(sessionsDir, sessionId, value);
     }
     if (Array.isArray(value)) {
-        return Promise.all(value.map((entry) => resolveSessionBlobPointers(specDir, sessionId, entry)));
+        return Promise.all(value.map((entry) => resolveSessionBlobPointers(sessionsDir, sessionId, entry)));
     }
     if (isRecord(value)) {
         const next = {};
         for (const [key, child] of Object.entries(value)) {
-            next[key] = await resolveSessionBlobPointers(specDir, sessionId, child);
+            next[key] = await resolveSessionBlobPointers(sessionsDir, sessionId, child);
         }
         return next;
     }
@@ -482,8 +558,8 @@ function extractLastEventSeq(content) {
  * Reads a bounded tail slice for O(1) seq lookup; falls back to full scan only
  * if the tail slice cannot be parsed (for example, partial line boundary).
  */
-async function getNextEventSeq(specDir, sessionId) {
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+async function getNextEventSeq(sessionsDir, sessionId) {
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     let fileHandle = null;
     try {
         fileHandle = await fsPromises.open(eventsPath, "r");
@@ -537,17 +613,17 @@ async function getNextEventSeq(specDir, sessionId) {
  * (single-process, sequential event logging). If concurrent access is needed
  * in the future, consider file locking or an in-memory counter per session.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param input - Event input (ts and seq are auto-assigned if not provided)
  * @returns The appended event with auto-assigned fields
  */
-export async function appendEvent(specDir, input) {
-    const sessionDir = getSessionDir(specDir, input.session_id);
-    const eventsPath = getSessionEventsPath(specDir, input.session_id);
+export async function appendEvent(sessionsDir, input) {
+    const sessionDir = getSessionDir(sessionsDir, input.session_id);
+    const eventsPath = getSessionEventsPath(sessionsDir, input.session_id);
     // Ensure session directory exists (lazy creation)
     await fsPromises.mkdir(sessionDir, { recursive: true });
     // Derive next sequence number from the last stored event.
-    const seq = input.seq ?? (await getNextEventSeq(specDir, input.session_id));
+    const seq = input.seq ?? (await getNextEventSeq(sessionsDir, input.session_id));
     // Build full event
     const event = {
         ts: input.ts ?? Date.now(),
@@ -559,8 +635,8 @@ export async function appendEvent(specDir, input) {
     };
     // AC: @session-events ac-8, ac-9 - Externalize oversized payload fields
     // before writing to events.jsonl.
-    const externalizedData = await externalizeOversizedPayloads(specDir, input.session_id, seq, event.data, [], {
-        blobDir: getSessionBlobDir(specDir, input.session_id),
+    const externalizedData = await externalizeOversizedPayloads(sessionsDir, input.session_id, seq, event.data, [], {
+        blobDir: getSessionBlobDir(sessionsDir, input.session_id),
         ensuredDir: false,
     });
     const eventWithGuardrails = {
@@ -574,10 +650,10 @@ export async function appendEvent(specDir, input) {
     let line = JSON.stringify(validated);
     if (Buffer.byteLength(line, "utf-8") > EVENT_LINE_MAX_BYTES) {
         const blobContext = {
-            blobDir: getSessionBlobDir(specDir, input.session_id),
+            blobDir: getSessionBlobDir(sessionsDir, input.session_id),
             ensuredDir: false,
         };
-        const fullDataPointer = await createBlobPointer(specDir, input.session_id, seq, [], validated.data, blobContext);
+        const fullDataPointer = await createBlobPointer(sessionsDir, input.session_id, seq, [], validated.data, blobContext);
         validated = SessionEventSchema.parse({
             ...validated,
             data: fullDataPointer,
@@ -599,10 +675,10 @@ export async function appendEvent(specDir, input) {
  * Writes are atomic (temp-file then rename). When dryRun is enabled, no files
  * are modified and no blob files are written.
  */
-export async function compactSessionEvents(specDir, sessionId, options = {}) {
+export async function compactSessionEvents(sessionsDir, sessionId, options = {}) {
     const dryRun = options.dryRun === true;
     const renameFn = options.renameFn ?? fsPromises.rename;
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     let content;
     try {
         content = await fsPromises.readFile(eventsPath, "utf-8");
@@ -639,7 +715,7 @@ export async function compactSessionEvents(specDir, sessionId, options = {}) {
         };
     }
     const blobContext = {
-        blobDir: getSessionBlobDir(specDir, sessionId),
+        blobDir: getSessionBlobDir(sessionsDir, sessionId),
         ensuredDir: false,
         dryRun,
         createdBlobs: 0,
@@ -656,14 +732,14 @@ export async function compactSessionEvents(specDir, sessionId, options = {}) {
             throw new Error(`Invalid JSON in events log at line ${i + 1}: ${err instanceof Error ? err.message : String(err)}`);
         }
         const event = SessionEventSchema.parse(parsed);
-        const externalizedData = await externalizeOversizedPayloads(specDir, sessionId, event.seq, event.data, [], blobContext);
+        const externalizedData = await externalizeOversizedPayloads(sessionsDir, sessionId, event.seq, event.data, [], blobContext);
         let validated = SessionEventSchema.parse({
             ...event,
             data: externalizedData,
         });
         let compactedLine = JSON.stringify(validated);
         if (Buffer.byteLength(compactedLine, "utf-8") > EVENT_LINE_MAX_BYTES) {
-            const fullDataPointer = await createBlobPointer(specDir, sessionId, event.seq, [], validated.data, blobContext);
+            const fullDataPointer = await createBlobPointer(sessionsDir, sessionId, event.seq, [], validated.data, blobContext);
             validated = SessionEventSchema.parse({
                 ...validated,
                 data: fullDataPointer,
@@ -688,7 +764,7 @@ export async function compactSessionEvents(specDir, sessionId, options = {}) {
         };
     }
     if (!dryRun) {
-        const sessionDir = getSessionDir(specDir, sessionId);
+        const sessionDir = getSessionDir(sessionsDir, sessionId);
         const tmpPath = path.join(sessionDir, `.${EVENTS_FILE}.${process.pid}.${Date.now()}.tmp`);
         try {
             await fsPromises.writeFile(tmpPath, compactedContent, "utf-8");
@@ -699,6 +775,10 @@ export async function compactSessionEvents(specDir, sessionId, options = {}) {
             throw err;
         }
     }
+    // AC: @session-branch-worktree ac-commit-boundaries — commit on compact
+    if (!dryRun) {
+        await commitAtLifecycleBoundary(sessionsDir, `session: compact (${sessionId})`);
+    }
     return {
         events_processed: sourceLines.length,
         blobs_created: blobContext.createdBlobs ?? 0,
@@ -715,12 +795,12 @@ export async function compactSessionEvents(specDir, sessionId, options = {}) {
  *
  * AC-4: Returns all events in sequence order.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Array of events sorted by sequence number
  */
-export async function readEvents(specDir, sessionId) {
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+export async function readEvents(sessionsDir, sessionId) {
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     try {
         const content = await fsPromises.readFile(eventsPath, "utf-8");
         const lines = content
@@ -745,6 +825,45 @@ export async function readEvents(specDir, sessionId) {
         return [];
     }
 }
+/**
+ * Read a single event by sequence number from a session's event log.
+ *
+ * Scans events.jsonl line-by-line and stops as soon as the matching seq is
+ * found, avoiding full parsing of all events for large sessions.
+ *
+ * AC: @session-event-detail-endpoint ac-single-event-fetch
+ *
+ * @param sessionsDir - The sessions directory path
+ * @param sessionId - Session ID
+ * @param seq - Sequence number to find
+ * @returns The matching event, or null if not found
+ */
+export async function readEventBySeq(sessionsDir, sessionId, seq) {
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
+    let content;
+    try {
+        content = await fsPromises.readFile(eventsPath, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const lines = content.split("\n");
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (trimmed.length === 0)
+            continue;
+        try {
+            const raw = JSON.parse(trimmed);
+            if (isRecord(raw) && raw.seq === seq) {
+                return SessionEventSchema.parse(raw);
+            }
+        }
+        catch {
+            // Skip invalid lines
+        }
+    }
+    return null;
+}
 /**
  * Deduplicate phased tool_call events.
  *
@@ -794,14 +913,14 @@ export function deduplicatePhasedToolCalls(events) {
 /**
  * Read events within a time range.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param since - Start timestamp (inclusive)
  * @param until - End timestamp (inclusive)
  * @returns Array of events within the time range
  */
-export async function readEventsSince(specDir, sessionId, since, until) {
-    const events = await readEvents(specDir, sessionId);
+export async function readEventsSince(sessionsDir, sessionId, since, until) {
+    const events = await readEvents(sessionsDir, sessionId);
     return events.filter((e) => {
         if (e.ts < since)
             return false;
@@ -813,12 +932,12 @@ export async function readEventsSince(specDir, sessionId, since, until) {
 /**
  * Get the last event in a session.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns The last event or null if no events
  */
-export async function getLastEvent(specDir, sessionId) {
-    const events = await readEvents(specDir, sessionId);
+export async function getLastEvent(sessionsDir, sessionId) {
+    const events = await readEvents(sessionsDir, sessionId);
     if (events.length === 0) {
         return null;
     }
@@ -906,8 +1025,8 @@ export function resolveStaleSessionCriteria(input) {
  * Unlike readEvents(), this is strict: corrupt events are surfaced as failures
  * so stale auto-close can skip unsafe sessions.
  */
-export async function getSessionActivityForStaleCheck(specDir, sessionId) {
-    const metadata = await getSession(specDir, sessionId);
+export async function getSessionActivityForStaleCheck(sessionsDir, sessionId) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata) {
         return {
             ok: false,
@@ -923,7 +1042,7 @@ export async function getSessionActivityForStaleCheck(specDir, sessionId) {
             detail: `Session ${sessionId} has invalid started_at timestamp`,
         };
     }
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     let content;
     try {
         content = await fsPromises.readFile(eventsPath, "utf-8");
@@ -1019,21 +1138,21 @@ export function evaluateStaleSession(startedAt, activity, criteria, nowMs = Date
         eligible,
     };
 }
-export async function selectStaleActiveSessions(specDir, criteriaInput = {}, nowMs = Date.now()) {
+export async function selectStaleActiveSessions(sessionsDir, criteriaInput = {}, nowMs = Date.now()) {
     const criteriaResolved = resolveStaleSessionCriteria(criteriaInput);
     if (!criteriaResolved.ok) {
         throw new Error(`${criteriaResolved.message}. ${criteriaResolved.guidance}`);
     }
     const criteria = criteriaResolved.criteria;
-    const sessionIds = await listSessions(specDir);
+    const sessionIds = await listSessions(sessionsDir);
     const evaluations = [];
     const candidates = [];
     const skipped = [];
     for (const sessionId of sessionIds) {
-        const metadata = await getSession(specDir, sessionId);
+        const metadata = await getSession(sessionsDir, sessionId);
         if (!metadata || metadata.status !== "active")
             continue;
-        const activityResult = await getSessionActivityForStaleCheck(specDir, sessionId);
+        const activityResult = await getSessionActivityForStaleCheck(sessionsDir, sessionId);
         if (!activityResult.ok) {
             skipped.push({
                 sessionId,
@@ -1081,9 +1200,9 @@ export function buildAutoAbandonedCloseReason(criteria, evaluation) {
  * Apply abandoned metadata to stale session candidates.
  *
  * All updates in a single invocation share one ended_at timestamp, which lets
- * the caller persist and commit the batch atomically with one shadow commit.
+ * the caller persist and commit the batch atomically.
  */
-export async function applyAutoAbandonMetadata(specDir, selection, options) {
+export async function applyAutoAbandonMetadata(sessionsDir, selection, options) {
     const dryRun = options?.dryRun === true;
     const endedAt = new Date(options?.nowMs ?? Date.now()).toISOString();
     const updates = [];
@@ -1097,7 +1216,7 @@ export async function applyAutoAbandonMetadata(specDir, selection, options) {
         });
         if (dryRun)
             continue;
-        const metadata = await getSession(specDir, candidate.sessionId);
+        const metadata = await getSession(sessionsDir, candidate.sessionId);
         if (!metadata)
             continue;
         const updated = {
@@ -1106,7 +1225,7 @@ export async function applyAutoAbandonMetadata(specDir, selection, options) {
             ended_at: endedAt,
             close_reason: closeReason,
         };
-        const metadataPath = getSessionMetadataPath(specDir, candidate.sessionId);
+        const metadataPath = getSessionMetadataPath(sessionsDir, candidate.sessionId);
         const content = YAML.stringify(updated, {
             indent: 2,
             lineWidth: 100,
@@ -1114,15 +1233,14 @@ export async function applyAutoAbandonMetadata(specDir, selection, options) {
         });
         await fsPromises.writeFile(metadataPath, content, "utf-8");
     }
-    let shadowCommitted;
-    if (!dryRun && updates.length > 0 && options?.shadowCommitMessage) {
-        shadowCommitted = await shadowAutoCommit(specDir, options.shadowCommitMessage);
+    // AC: @session-branch-worktree ac-commit-boundaries — commit on stale cleanup
+    if (!dryRun && updates.length > 0) {
+        await commitAtLifecycleBoundary(sessionsDir, `session: stale cleanup (${updates.length} abandoned)`);
     }
     return {
         dryRun,
         updatedCount: updates.length,
         updates,
-        shadowCommitted,
     };
 }
 // ─── Session Log Summaries ───────────────────────────────────────────────────
@@ -1143,8 +1261,8 @@ function resolveSessionType(metadata) {
  * Count lines in events.jsonl without parsing JSON.
  * Much faster than readEvents() for large files.
  */
-async function countEventLines(specDir, sessionId) {
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+async function countEventLines(sessionsDir, sessionId) {
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     try {
         const content = await fsPromises.readFile(eventsPath, "utf-8");
         if (!content.trim())
@@ -1158,8 +1276,8 @@ async function countEventLines(specDir, sessionId) {
 /**
  * Count context-iter-*.json files for a session (iteration count).
  */
-async function countIterations(specDir, sessionId) {
-    const sessionDir = getSessionDir(specDir, sessionId);
+async function countIterations(sessionsDir, sessionId) {
+    const sessionDir = getSessionDir(sessionsDir, sessionId);
     try {
         const entries = await fsPromises.readdir(sessionDir);
         return entries.filter((e) => e.startsWith("context-iter-") && e.endsWith(".json")).length;
@@ -1181,8 +1299,8 @@ async function countIterations(specDir, sessionId) {
  *
  * We use a fast substring check before JSON parsing for performance.
  */
-async function countTaskCompletions(specDir, sessionId) {
-    const eventsPath = getSessionEventsPath(specDir, sessionId);
+async function countTaskCompletions(sessionsDir, sessionId) {
+    const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
     try {
         const content = await fsPromises.readFile(eventsPath, "utf-8");
         if (!content.trim())
@@ -1221,18 +1339,18 @@ async function countTaskCompletions(specDir, sessionId) {
  *
  * Gathers metadata and computes metrics lazily (only parses what's needed).
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Session summary or null if session doesn't exist
  */
-export async function getSessionLogSummary(specDir, sessionId) {
-    const metadata = await getSession(specDir, sessionId);
+export async function getSessionLogSummary(sessionsDir, sessionId) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata)
         return null;
     const [eventCount, iterationCount, tasksCompleted] = await Promise.all([
-        countEventLines(specDir, sessionId),
-        countIterationsBoundaryAware(specDir, sessionId),
-        countTaskCompletions(specDir, sessionId),
+        countEventLines(sessionsDir, sessionId),
+        countIterationsBoundaryAware(sessionsDir, sessionId),
+        countTaskCompletions(sessionsDir, sessionId),
     ]);
     const startMs = new Date(metadata.started_at).getTime();
     const endMs = metadata.ended_at
@@ -1243,7 +1361,10 @@ export async function getSessionLogSummary(specDir, sessionId) {
         id: metadata.id,
         status: metadata.status,
         agent_type: metadata.agent_type,
+        agent_id: metadata.agent_id,
         session_type: resolveSessionType(metadata),
+        trigger: metadata.trigger,
+        task_id: metadata.task_id,
         started_at: metadata.started_at,
         ended_at: metadata.ended_at,
         duration_ms: durationMs,
@@ -1252,15 +1373,48 @@ export async function getSessionLogSummary(specDir, sessionId) {
         tasks_completed: tasksCompleted,
     };
 }
+/**
+ * Get session metadata only — reads session.yaml without touching events.jsonl.
+ *
+ * AC: @session-list-pagination-api ac-metadata-only — List endpoint reads only
+ * session.yaml metadata.
+ * AC: @session-summary-cache ac-persist-on-close — Closed sessions have stats
+ * persisted in metadata; read them instead of hardcoding 0.
+ */
+export async function getSessionMetadataOnly(sessionsDir, sessionId) {
+    const metadata = await getSession(sessionsDir, sessionId);
+    if (!metadata)
+        return null;
+    const startMs = new Date(metadata.started_at).getTime();
+    const endMs = metadata.ended_at
+        ? new Date(metadata.ended_at).getTime()
+        : Date.now();
+    const durationMs = endMs - startMs;
+    return {
+        id: metadata.id,
+        status: metadata.status,
+        agent_type: metadata.agent_type,
+        agent_id: metadata.agent_id,
+        session_type: resolveSessionType(metadata),
+        trigger: metadata.trigger,
+        task_id: metadata.task_id,
+        started_at: metadata.started_at,
+        ended_at: metadata.ended_at,
+        duration_ms: durationMs,
+        event_count: metadata.event_count ?? 0,
+        iteration_count: metadata.iteration_count ?? 0,
+        tasks_completed: metadata.tasks_completed ?? 0,
+    };
+}
 /**
  * Get summaries for all sessions.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @returns Array of session summaries
  */
-export async function getAllSessionLogSummaries(specDir) {
-    const sessionIds = await listSessions(specDir);
-    const summaries = await Promise.all(sessionIds.map((id) => getSessionLogSummary(specDir, id)));
+export async function getAllSessionLogSummaries(sessionsDir) {
+    const sessionIds = await listSessions(sessionsDir);
+    const summaries = await Promise.all(sessionIds.map((id) => getSessionLogSummary(sessionsDir, id)));
     return summaries.filter((s) => s !== null);
 }
 // ─── Context Snapshots ───────────────────────────────────────────────────────
@@ -1270,14 +1424,14 @@ export async function getAllSessionLogSummaries(specDir) {
  * This creates an audit trail of what context the agent saw at each iteration,
  * useful for debugging and reviewing agent behavior.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param iteration - Iteration number
  * @param context - The session context data
  */
-export async function saveSessionContext(specDir, sessionId, iteration, context) {
-    const sessionDir = getSessionDir(specDir, sessionId);
-    const contextPath = getSessionContextPath(specDir, sessionId, iteration);
+export async function saveSessionContext(sessionsDir, sessionId, iteration, context) {
+    const sessionDir = getSessionDir(sessionsDir, sessionId);
+    const contextPath = getSessionContextPath(sessionsDir, sessionId, iteration);
     // Ensure session directory exists
     await fsPromises.mkdir(sessionDir, { recursive: true });
     // Write context snapshot as pretty JSON
@@ -1287,13 +1441,13 @@ export async function saveSessionContext(specDir, sessionId, iteration, context)
 /**
  * Read session context snapshot for a given iteration.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param iteration - Iteration number
  * @returns The context snapshot or null if not found
  */
-export async function readSessionContext(specDir, sessionId, iteration) {
-    const contextPath = getSessionContextPath(specDir, sessionId, iteration);
+export async function readSessionContext(sessionsDir, sessionId, iteration) {
+    const contextPath = getSessionContextPath(sessionsDir, sessionId, iteration);
     try {
         const content = await fsPromises.readFile(contextPath, "utf-8");
         return JSON.parse(content);
@@ -1307,12 +1461,12 @@ export async function readSessionContext(specDir, sessionId, iteration) {
  *
  * AC: @session-log-show ac-7, ac-8, ac-9
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param idOrPrefix - Full session ID or prefix (e.g., first 8 chars)
  * @returns Resolution result
  */
-export async function resolveSessionId(specDir, idOrPrefix) {
-    const sessionIds = await listSessions(specDir);
+export async function resolveSessionId(sessionsDir, idOrPrefix) {
+    const sessionIds = await listSessions(sessionsDir);
     // First, try exact match
     if (sessionIds.includes(idOrPrefix)) {
         return { ok: true, id: idOrPrefix };
@@ -1331,8 +1485,8 @@ export async function resolveSessionId(specDir, idOrPrefix) {
 /**
  * Get iteration number from a context snapshot file.
  */
-async function getIterationNumbers(specDir, sessionId) {
-    const sessionDir = getSessionDir(specDir, sessionId);
+async function getIterationNumbers(sessionsDir, sessionId) {
+    const sessionDir = getSessionDir(sessionsDir, sessionId);
     try {
         const entries = await fsPromises.readdir(sessionDir);
         const iterations = [];
@@ -1524,14 +1678,14 @@ function boundaryIterationGrouping(events, boundaries) {
  *
  * AC: @session-log-show ac-2, ac-10
  */
-async function computeIterationSummaries(specDir, sessionId) {
-    const events = await readEvents(specDir, sessionId);
+async function computeIterationSummaries(sessionsDir, sessionId) {
+    const events = await readEvents(sessionsDir, sessionId);
     const boundaries = findIterationBoundaries(events);
     if (boundaries.length > 0) {
         return boundaryIterationGrouping(events, boundaries);
     }
     // Legacy fallback: no prompt.sent boundaries with phase "task-work"
-    const snapshotIterations = await getIterationNumbers(specDir, sessionId);
+    const snapshotIterations = await getIterationNumbers(sessionsDir, sessionId);
     return legacyIterationGrouping(events, snapshotIterations);
 }
 /**
@@ -1542,14 +1696,14 @@ async function computeIterationSummaries(specDir, sessionId) {
  *
  * Falls back to counting context-iter-*.json files when no boundaries exist.
  */
-async function countIterationsBoundaryAware(specDir, sessionId) {
-    const events = await readEvents(specDir, sessionId);
+async function countIterationsBoundaryAware(sessionsDir, sessionId) {
+    const events = await readEvents(sessionsDir, sessionId);
     const boundaries = findIterationBoundaries(events);
     if (boundaries.length > 0) {
         return boundaries.length;
     }
     // Legacy fallback: count from context snapshots and event data
-    const snapshotIterations = await getIterationNumbers(specDir, sessionId);
+    const snapshotIterations = await getIterationNumbers(sessionsDir, sessionId);
     const allIterations = new Set(snapshotIterations);
     for (const event of events) {
         const data = event.data;
@@ -1562,17 +1716,17 @@ async function countIterationsBoundaryAware(specDir, sessionId) {
 /**
  * Get full session detail for session log show.
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID (must be resolved first)
  * @returns Session detail or null if not found
  */
-export async function getSessionLogDetail(specDir, sessionId) {
-    const metadata = await getSession(specDir, sessionId);
+export async function getSessionLogDetail(sessionsDir, sessionId) {
+    const metadata = await getSession(sessionsDir, sessionId);
     if (!metadata)
         return null;
     const [eventCount, iterations] = await Promise.all([
-        countEventLines(specDir, sessionId),
-        computeIterationSummaries(specDir, sessionId),
+        countEventLines(sessionsDir, sessionId),
+        computeIterationSummaries(sessionsDir, sessionId),
     ]);
     const startMs = new Date(metadata.started_at).getTime();
     const endMs = metadata.ended_at
@@ -1624,6 +1778,7 @@ export function computeSessionLogStats(summaries) {
         abandoned: 0,
         timed_out: 0,
         failed: 0,
+        stalled: 0,
     };
     for (const s of summaries) {
         totalEvents += s.event_count;
@@ -1635,7 +1790,7 @@ export function computeSessionLogStats(summaries) {
     const n = summaries.length;
     // Build status breakdown
     const statusBreakdown = [];
-    for (const status of ["completed", "active", "abandoned", "timed_out", "failed"]) {
+    for (const status of ["completed", "active", "abandoned", "timed_out", "failed", "stalled"]) {
         const count = statusCounts[status] || 0;
         if (count > 0) {
             statusBreakdown.push({
@@ -1665,11 +1820,11 @@ export function computeSessionLogStats(summaries) {
  *
  * AC: @session-log-stats ac-6
  */
-export async function computeToolUsageStats(specDir, sessionIds, limit = 10) {
+export async function computeToolUsageStats(sessionsDir, sessionIds, limit = 10) {
     const toolCounts = {};
     let totalToolCalls = 0;
     for (const sessionId of sessionIds) {
-        const eventsPath = getSessionEventsPath(specDir, sessionId);
+        const eventsPath = getSessionEventsPath(sessionsDir, sessionId);
         try {
             const content = await fsPromises.readFile(eventsPath, "utf-8");
             if (!content.trim())
@@ -1824,34 +1979,45 @@ function extractContentExcerpt(data, pattern, maxLength = 200) {
  *
  * AC: @session-log-search ac-1, ac-2, ac-3, ac-5, ac-7
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param pattern - Case-insensitive substring to search for
  * @param options - Search filtering options
  * @returns Array of search results grouped by session
  */
-export async function searchSessionEvents(specDir, pattern, options = {}) {
+export async function searchSessionEvents(sessionsDir, pattern, options = {}) {
     // Defense-in-depth: normalize limit to a valid positive integer
     const rawLimit = options.limit ?? 50;
     const limit = Number.isNaN(rawLimit) || rawLimit <= 0 ? 50 : rawLimit;
     const lowerPattern = pattern.toLowerCase();
     const resolveBlobs = options.resolveBlobs ?? false;
-    // Get all session summaries for metadata filtering
-    const allSummaries = await getAllSessionLogSummaries(specDir);
-    // AC: @session-log-search ac-3 - Pre-filter by --since
-    let filteredSummaries = allSummaries;
-    if (options.sinceDate) {
-        filteredSummaries = filteredSummaries.filter((s) => new Date(s.started_at) >= options.sinceDate);
+    // Use pre-filtered session IDs if provided, otherwise load and filter
+    let filteredSummaries;
+    if (options.sessionSummaries) {
+        filteredSummaries = [...options.sessionSummaries];
     }
-    // AC: @session-log-search ac-7 - Pre-filter by --agent
-    if (options.agentType) {
-        filteredSummaries = filteredSummaries.filter((s) => s.agent_type === options.agentType);
+    else if (options.sessionIds) {
+        const idSet = new Set(options.sessionIds);
+        const allSummaries = await getAllSessionLogSummaries(sessionsDir);
+        filteredSummaries = allSummaries.filter((s) => idSet.has(s.id));
+    }
+    else {
+        const allSummaries = await getAllSessionLogSummaries(sessionsDir);
+        // AC: @session-log-search ac-3 - Pre-filter by --since
+        filteredSummaries = allSummaries;
+        if (options.sinceDate) {
+            filteredSummaries = filteredSummaries.filter((s) => new Date(s.started_at) >= options.sinceDate);
+        }
+        // AC: @session-log-search ac-7 - Pre-filter by --agent
+        if (options.agentType) {
+            filteredSummaries = filteredSummaries.filter((s) => s.agent_type === options.agentType);
+        }
     }
     const results = [];
     let totalMatches = 0;
     for (const summary of filteredSummaries) {
         if (totalMatches >= limit)
             break;
-        const eventsPath = getSessionEventsPath(specDir, summary.id);
+        const eventsPath = getSessionEventsPath(sessionsDir, summary.id);
         let content;
         try {
             content = await fsPromises.readFile(eventsPath, "utf-8");
@@ -1890,7 +2056,7 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
                     }
                 }
                 const searchableData = resolveBlobs
-                    ? await resolveSessionBlobPointers(specDir, summary.id, event.data)
+                    ? await resolveSessionBlobPointers(sessionsDir, summary.id, event.data)
                     : event.data;
                 // Verify match in stringified data (not just line, in case pattern
                 // appears in metadata)
@@ -1900,6 +2066,7 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
                 // AC: @session-log-search ac-4 - Create match with excerpt
                 matches.push({
                     session_id: summary.id,
+                    event_seq: typeof event.seq === "number" ? event.seq : -1,
                     timestamp: event.ts,
                     event_type: event.type,
                     content_excerpt: extractContentExcerpt(searchableData, pattern, 200),
@@ -1934,13 +2101,13 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
  * AC: @session-creation-and-env-injection ac-budget-local
  * AC: @session-creation-and-env-injection ac-library
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param input - Session creation parameters
  * @returns Session metadata and optional budget (no console output)
  */
-export async function createSessionWithBudget(specDir, input) {
+export async function createSessionWithBudget(sessionsDir, input) {
     // Create session
-    const session = await createSession(specDir, {
+    const session = await createSession(sessionsDir, {
         id: input.id,
         agent_type: input.agent_type,
         task_id: input.task_id,
@@ -1948,7 +2115,7 @@ export async function createSessionWithBudget(specDir, input) {
     // Optionally create budget
     let budget = null;
     if (input.budget !== undefined && input.budget > 0) {
-        budget = await createBudget(specDir, input.id, input.budget);
+        budget = await createBudget(sessionsDir, input.id, input.budget);
     }
     return {
         session_id: input.id,
@@ -2315,13 +2482,13 @@ export async function removeEnvForAdapter(adapterId, previousValue) {
  *
  * AC: @session-creation-and-env-injection ac-invalid-session
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - The session ID to validate
  * @returns Validation result with error details if invalid
  */
-export async function validateSessionId(specDir, sessionId) {
+export async function validateSessionId(sessionsDir, sessionId) {
     // Check if session directory exists
-    const exists = await sessionExists(specDir, sessionId);
+    const exists = await sessionExists(sessionsDir, sessionId);
     if (!exists) {
         return {
             valid: false,
@@ -2330,7 +2497,7 @@ export async function validateSessionId(specDir, sessionId) {
         };
     }
     // Try to read and validate session metadata
-    const session = await getSession(specDir, sessionId);
+    const session = await getSession(sessionsDir, sessionId);
     if (!session) {
         return {
             valid: false,
@@ -2357,24 +2524,24 @@ async function writeBudgetAtomic(filePath, budget) {
 /**
  * Create a budget for a session.
  *
- * Writes budget.json to .kspec/sessions/{id}/ on the local filesystem
+ * Writes budget.json to .kspec-sessions/{id}/ on the local filesystem
  * (NOT committed to shadow branch).
  *
  * AC: @session-creation-and-env-injection ac-budget
  * AC: @session-creation-and-env-injection ac-budget-local
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @param maxPerCycle - Maximum tasks allowed per cycle
  * @returns The created budget
  */
-export async function createBudget(specDir, sessionId, maxPerCycle) {
+export async function createBudget(sessionsDir, sessionId, maxPerCycle) {
     const budget = {
         max_per_cycle: maxPerCycle,
         started_this_cycle: 0,
     };
     const validated = TaskBudgetSchema.parse(budget);
-    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    const budgetPath = getSessionBudgetPath(sessionsDir, sessionId);
     await writeBudgetAtomic(budgetPath, validated);
     return validated;
 }
@@ -2383,12 +2550,12 @@ export async function createBudget(specDir, sessionId, maxPerCycle) {
  *
  * AC: @task-budget-enforcement ac-no-budget
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Budget or null if no budget configured (opt-in)
  */
-export async function getBudget(specDir, sessionId) {
-    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+export async function getBudget(sessionsDir, sessionId) {
+    const budgetPath = getSessionBudgetPath(sessionsDir, sessionId);
     let content;
     try {
         content = await fsPromises.readFile(budgetPath, "utf-8");
@@ -2414,16 +2581,24 @@ export async function getBudget(specDir, sessionId) {
  * AC: @task-budget-enforcement ac-no-budget
  * AC: @task-budget-enforcement ac-no-session
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID, or undefined if KSPEC_SESSION_ID not set
  * @returns Budget check result
  */
-export async function checkBudget(specDir, sessionId) {
+export async function checkBudget(sessionsDir, sessionId) {
     // AC: @task-budget-enforcement ac-no-session — no session means no check
     if (!sessionId) {
         return { allowed: true };
     }
-    const budget = await getBudget(specDir, sessionId);
+    // Skip budget enforcement when session exists but is not active (stale KSPEC_SESSION_ID).
+    // A completed, abandoned, timed_out, failed, or stalled session should not block task starts.
+    // If session metadata is missing, proceed with normal budget checks — the budget file
+    // itself is the authority on whether enforcement applies.
+    const session = await getSession(sessionsDir, sessionId);
+    if (session && session.status !== "active") {
+        return { allowed: true };
+    }
+    const budget = await getBudget(sessionsDir, sessionId);
     // AC: @task-budget-enforcement ac-no-budget — no budget means no check
     if (!budget) {
         return { allowed: true };
@@ -2448,12 +2623,12 @@ export async function checkBudget(specDir, sessionId) {
  * AC: @task-budget-enforcement ac-increment
  * AC: @task-budget-enforcement ac-atomic-write
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Updated budget, or null if no budget configured
  */
-export async function incrementBudget(specDir, sessionId) {
-    const budget = await getBudget(specDir, sessionId);
+export async function incrementBudget(sessionsDir, sessionId) {
+    const budget = await getBudget(sessionsDir, sessionId);
     if (!budget) {
         return null;
     }
@@ -2462,7 +2637,7 @@ export async function incrementBudget(specDir, sessionId) {
         started_this_cycle: budget.started_this_cycle + 1,
     };
     const validated = TaskBudgetSchema.parse(updated);
-    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    const budgetPath = getSessionBudgetPath(sessionsDir, sessionId);
     await writeBudgetAtomic(budgetPath, validated);
     return validated;
 }
@@ -2475,12 +2650,12 @@ export async function incrementBudget(specDir, sessionId) {
  * AC: @task-budget-enforcement ac-reset
  * AC: @task-budget-enforcement ac-atomic-write
  *
- * @param specDir - The .kspec directory path
+ * @param sessionsDir - The .kspec directory path
  * @param sessionId - Session ID
  * @returns Updated budget, or null if no budget configured
  */
-export async function resetBudget(specDir, sessionId) {
-    const budget = await getBudget(specDir, sessionId);
+export async function resetBudget(sessionsDir, sessionId) {
+    const budget = await getBudget(sessionsDir, sessionId);
     if (!budget) {
         return null;
     }
@@ -2489,7 +2664,7 @@ export async function resetBudget(specDir, sessionId) {
         started_this_cycle: 0,
     };
     const validated = TaskBudgetSchema.parse(updated);
-    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    const budgetPath = getSessionBudgetPath(sessionsDir, sessionId);
     await writeBudgetAtomic(budgetPath, validated);
     return validated;
 }