@kynetic-ai/spec 0.3.0 → 0.5.0

package/dist/sessions/store.js

@@ -15,11 +15,12 @@ import * as fs from "node:fs";
 import * as fsPromises from "node:fs/promises";
 import * as path from "node:path";
 import * as YAML from "yaml";
-import { SessionEventSchema, SessionMetadataSchema, } from "./types.js";
+import { SessionEventSchema, SessionMetadataSchema, TaskBudgetSchema, } from "./types.js";
 // ─── Constants ───────────────────────────────────────────────────────────────
 const SESSIONS_DIR = "sessions";
 const METADATA_FILE = "session.yaml";
 const EVENTS_FILE = "events.jsonl";
+const BUDGET_FILE = "budget.json";
 // ─── Path Helpers ────────────────────────────────────────────────────────────
 /**
  * Get the sessions directory path within a spec directory.
@@ -51,6 +52,13 @@ export function getSessionEventsPath(specDir, sessionId) {
 export function getSessionContextPath(specDir, sessionId, iteration) {
     return path.join(getSessionDir(specDir, 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);
+}
 // ─── Session CRUD ────────────────────────────────────────────────────────────
 /**
  * Create a new session with metadata.
@@ -165,6 +173,97 @@ export async function sessionExists(specDir, sessionId) {
         return false;
     }
 }
+// ─── End-Loop Signal ────────────────────────────────────────────────────────
+/**
+ * Request end-loop for a session.
+ *
+ * Writes end_requested=true and optional end_reason to the session metadata.
+ * This is the session-scoped replacement for the marker file approach.
+ *
+ * AC: @session-end-loop-signal ac-signal
+ *
+ * @param specDir - 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);
+    if (!metadata) {
+        return null;
+    }
+    const updated = {
+        ...metadata,
+        end_requested: true,
+        end_reason: reason,
+    };
+    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const content = YAML.stringify(updated, {
+        indent: 2,
+        lineWidth: 100,
+        sortMapEntries: false,
+    });
+    await fsPromises.writeFile(metadataPath, content, "utf-8");
+    return updated;
+}
+/**
+ * Check if end-loop has been requested for a session.
+ *
+ * Only returns requested=true for active sessions. If the session is
+ * completed or abandoned, the end-loop signal is no longer relevant
+ * (prevents stale KSPEC_SESSION_ID from blocking task starts).
+ *
+ * AC: @session-end-loop-signal ac-detect
+ *
+ * @param specDir - 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);
+    if (!metadata) {
+        return null;
+    }
+    return {
+        requested: metadata.end_requested === true && metadata.status === "active",
+        reason: metadata.end_reason,
+    };
+}
+/**
+ * Close a session with a specific status and reason.
+ *
+ * Used for all session close paths: normal exit, signal, error.
+ *
+ * AC: @session-end-loop-signal ac-session-close-normal
+ * 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 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);
+    if (!metadata) {
+        return null;
+    }
+    const updated = {
+        ...metadata,
+        status,
+        ended_at: new Date().toISOString(),
+        close_reason: reason,
+    };
+    const metadataPath = getSessionMetadataPath(specDir, sessionId);
+    const content = YAML.stringify(updated, {
+        indent: 2,
+        lineWidth: 100,
+        sortMapEntries: false,
+    });
+    await fsPromises.writeFile(metadataPath, content, "utf-8");
+    return updated;
+}
 // ─── Event Storage ───────────────────────────────────────────────────────────
 /**
  * Get the current event count for a session (for seq assignment).
@@ -264,6 +363,52 @@ export async function readEvents(specDir, sessionId) {
         return [];
     }
 }
+/**
+ * Deduplicate phased tool_call events.
+ *
+ * ACP SDK 0.14+ sends tool calls in two phases: first with empty rawInput,
+ * then with populated rawInput. This merges them by keeping only the version
+ * with populated rawInput per toolCallId.
+ */
+export function deduplicatePhasedToolCalls(events) {
+    // First pass: find toolCallIds that have a populated rawInput version
+    const populatedToolCalls = new Map(); // toolCallId → index
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        if (event.type !== "session.update")
+            continue;
+        const data = event.data;
+        const update = data?.update;
+        if (update?.sessionUpdate !== "tool_call")
+            continue;
+        const toolCallId = update.toolCallId || update.tool_call_id || update.id;
+        if (!toolCallId)
+            continue;
+        const rawInput = update.rawInput;
+        const hasContent = rawInput && Object.keys(rawInput).length > 0;
+        if (hasContent) {
+            populatedToolCalls.set(toolCallId, i);
+        }
+        else if (!populatedToolCalls.has(toolCallId)) {
+            // First (empty) version - track it in case no populated version exists
+            populatedToolCalls.set(toolCallId, i);
+        }
+    }
+    // Second pass: keep only the best version per toolCallId
+    return events.filter((event, i) => {
+        if (event.type !== "session.update")
+            return true;
+        const data = event.data;
+        const update = data?.update;
+        if (update?.sessionUpdate !== "tool_call")
+            return true;
+        const toolCallId = update.toolCallId || update.tool_call_id || update.id;
+        if (!toolCallId)
+            return true;
+        // Keep this event only if it's the best version (populated or only version)
+        return populatedToolCalls.get(toolCallId) === i;
+    });
+}
 /**
  * Read events within a time range.
  *
@@ -381,7 +526,7 @@ export async function getSessionLogSummary(specDir, sessionId) {
         return null;
     const [eventCount, iterationCount, tasksCompleted] = await Promise.all([
         countEventLines(specDir, sessionId),
-        countIterations(specDir, sessionId),
+        countIterationsBoundaryAware(specDir, sessionId),
         countTaskCompletions(specDir, sessionId),
     ]);
     const startMs = new Date(metadata.started_at).getTime();
@@ -506,17 +651,73 @@ function extractTaskRef(command) {
     return match ? match[0] : null;
 }
 /**
- * Compute per-iteration summaries from events.
+ * Find iteration boundaries from prompt.sent events with phase "task-work".
+ *
+ * Ralph emits these synchronously at the start of each iteration, so their
+ * array positions are reliable even when concurrent fire-and-forget events
+ * produce duplicate seq numbers.
+ *
+ * Returns validated, monotonically increasing boundaries.
+ */
+function findIterationBoundaries(events) {
+    const raw = [];
+    for (let i = 0; i < events.length; i++) {
+        const event = events[i];
+        if (event.type !== "prompt.sent")
+            continue;
+        const data = event.data;
+        if (data?.phase !== "task-work" ||
+            typeof data?.iteration !== "number") {
+            continue;
+        }
+        raw.push({ index: i, iteration: data.iteration });
+    }
+    // Validate: filter to monotonically increasing iteration numbers, deduplicate
+    const validated = [];
+    let lastIter = -Infinity;
+    for (const b of raw) {
+        if (b.iteration > lastIter) {
+            validated.push(b);
+            lastIter = b.iteration;
+        }
+    }
+    return validated;
+}
+/**
+ * Extract task start/complete refs from a slice of events.
+ */
+function extractTaskTransitions(events) {
+    const tasksStarted = [];
+    const tasksCompleted = [];
+    for (const event of events) {
+        if (event.type === "session.update") {
+            const data = event.data;
+            const command = data?.update?.rawInput?.command;
+            if (typeof command === "string") {
+                if (/\btask start\b/.test(command)) {
+                    const ref = extractTaskRef(command);
+                    if (ref)
+                        tasksStarted.push(ref);
+                }
+                else if (/\btask complete\b/.test(command)) {
+                    const ref = extractTaskRef(command);
+                    if (ref)
+                        tasksCompleted.push(ref);
+                }
+            }
+        }
+    }
+    return { tasksStarted, tasksCompleted };
+}
+/**
+ * Legacy iteration grouping: groups events by their data.iteration field.
  *
- * Dynamically creates iteration buckets based on both context snapshot files
- * AND event data to handle cases where events are logged before context
- * snapshots exist (e.g., active sessions).
+ * Used as fallback for sessions that don't have prompt.sent boundary events
+ * with phase "task-work" (pre-boundary sessions or non-ralph sessions).
  *
  * AC: @session-log-show ac-2
  */
-async function computeIterationSummaries(specDir, sessionId) {
-    const events = await readEvents(specDir, sessionId);
-    const snapshotIterations = await getIterationNumbers(specDir, sessionId);
+function legacyIterationGrouping(events, snapshotIterations) {
     // Collect all iteration numbers from both snapshots and events
     const allIterations = new Set(snapshotIterations);
     for (const event of events) {
@@ -525,14 +726,18 @@ async function computeIterationSummaries(specDir, sessionId) {
             allIterations.add(data.iteration);
         }
     }
-    // If no iterations found anywhere, create a single iteration-0 summary
+    // If no iterations found anywhere, synthesize iteration-0 only if events exist
     if (allIterations.size === 0) {
+        if (events.length === 0) {
+            return [];
+        }
+        const { tasksStarted, tasksCompleted } = extractTaskTransitions(events);
         return [
             {
                 iteration: 0,
                 event_count: events.length,
-                tasks_started: [],
-                tasks_completed: [],
+                tasks_started: tasksStarted,
+                tasks_completed: tasksCompleted,
             },
         ];
     }
@@ -543,41 +748,19 @@ async function computeIterationSummaries(specDir, sessionId) {
         iterationMap.set(n, []);
     }
     for (const event of events) {
-        // Try to get iteration from event data
         const data = event.data;
         const iter = data?.iteration;
         if (typeof iter === "number" && iterationMap.has(iter)) {
             iterationMap.get(iter).push(event);
         }
         else {
-            // Events without iteration info (lifecycle events) go to iteration 0
-            // or the first known iteration if 0 doesn't exist
             const fallbackIter = iterationMap.has(0) ? 0 : iterations[0];
             iterationMap.get(fallbackIter).push(event);
         }
     }
     const summaries = [];
     for (const [iterNum, iterEvents] of iterationMap) {
-        const tasksStarted = [];
-        const tasksCompleted = [];
-        for (const event of iterEvents) {
-            if (event.type === "session.update") {
-                const data = event.data;
-                const command = data?.update?.rawInput?.command;
-                if (typeof command === "string") {
-                    if (/\btask start\b/.test(command)) {
-                        const ref = extractTaskRef(command);
-                        if (ref)
-                            tasksStarted.push(ref);
-                    }
-                    else if (/\btask complete\b/.test(command)) {
-                        const ref = extractTaskRef(command);
-                        if (ref)
-                            tasksCompleted.push(ref);
-                    }
-                }
-            }
-        }
+        const { tasksStarted, tasksCompleted } = extractTaskTransitions(iterEvents);
         summaries.push({
             iteration: iterNum,
             event_count: iterEvents.length,
@@ -587,6 +770,83 @@ async function computeIterationSummaries(specDir, sessionId) {
     }
     return summaries.sort((a, b) => a.iteration - b.iteration);
 }
+/**
+ * Boundary-based iteration grouping: splits events by prompt.sent boundary
+ * positions (array indices) instead of trusting data.iteration fields.
+ *
+ * This is resilient to producer-side bugs where concurrent fire-and-forget
+ * event logging captures the wrong iteration number.
+ *
+ * AC: @session-log-show ac-10
+ */
+function boundaryIterationGrouping(events, boundaries) {
+    const summaries = [];
+    for (let b = 0; b < boundaries.length; b++) {
+        const startIdx = boundaries[b].index;
+        const endIdx = b + 1 < boundaries.length ? boundaries[b + 1].index : events.length;
+        const iterEvents = events.slice(startIdx, endIdx);
+        const { tasksStarted, tasksCompleted } = extractTaskTransitions(iterEvents);
+        summaries.push({
+            iteration: boundaries[b].iteration,
+            event_count: iterEvents.length,
+            tasks_started: tasksStarted,
+            tasks_completed: tasksCompleted,
+        });
+    }
+    // Pre-boundary events (before the first prompt.sent) merge into first iteration
+    if (boundaries.length > 0 && boundaries[0].index > 0) {
+        const preBoundaryEvents = events.slice(0, boundaries[0].index);
+        const { tasksStarted, tasksCompleted } = extractTaskTransitions(preBoundaryEvents);
+        summaries[0].event_count += preBoundaryEvents.length;
+        summaries[0].tasks_started = [...tasksStarted, ...summaries[0].tasks_started];
+        summaries[0].tasks_completed = [...tasksCompleted, ...summaries[0].tasks_completed];
+    }
+    return summaries;
+}
+/**
+ * Compute per-iteration summaries from events.
+ *
+ * Uses prompt.sent boundary events (phase: "task-work") when available for
+ * accurate index-based grouping. Falls back to legacy data.iteration grouping
+ * for sessions without boundaries.
+ *
+ * AC: @session-log-show ac-2, ac-10
+ */
+async function computeIterationSummaries(specDir, sessionId) {
+    const events = await readEvents(specDir, 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);
+    return legacyIterationGrouping(events, snapshotIterations);
+}
+/**
+ * Count iterations using boundary-aware logic, without computing full summaries.
+ *
+ * For use in getSessionLogSummary() (session log list, session log stats) to
+ * ensure iteration_count agrees with session log show.
+ *
+ * Falls back to counting context-iter-*.json files when no boundaries exist.
+ */
+async function countIterationsBoundaryAware(specDir, sessionId) {
+    const events = await readEvents(specDir, 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 allIterations = new Set(snapshotIterations);
+    for (const event of events) {
+        const data = event.data;
+        if (typeof data?.iteration === "number") {
+            allIterations.add(data.iteration);
+        }
+    }
+    return allIterations.size || (events.length > 0 ? 1 : 0);
+}
 /**
  * Get full session detail for session log show.
  *
@@ -598,9 +858,8 @@ export async function getSessionLogDetail(specDir, sessionId) {
     const metadata = await getSession(specDir, sessionId);
     if (!metadata)
         return null;
-    const [eventCount, iterationCount, iterations] = await Promise.all([
+    const [eventCount, iterations] = await Promise.all([
         countEventLines(specDir, sessionId),
-        countIterations(specDir, sessionId),
         computeIterationSummaries(specDir, sessionId),
     ]);
     const startMs = new Date(metadata.started_at).getTime();
@@ -617,7 +876,7 @@ export async function getSessionLogDetail(specDir, sessionId) {
         ended_at: metadata.ended_at,
         duration_ms: durationMs,
         event_count: eventCount,
-        iteration_count: iterationCount,
+        iteration_count: iterations.length,
         iterations,
     };
 }
@@ -701,6 +960,8 @@ export async function computeToolUsageStats(specDir, sessionIds, limit = 10) {
             if (!content.trim())
                 continue;
             const lines = content.trim().split("\n");
+            // Track seen toolCallIds to deduplicate phased events
+            const seenToolCallIds = new Set();
             for (const line of lines) {
                 // Quick pre-filter: only parse lines that might be tool_call events
                 if (!line.includes('"tool_call"'))
@@ -710,6 +971,12 @@ export async function computeToolUsageStats(specDir, sessionIds, limit = 10) {
                     if (event?.type === "session.update") {
                         const update = event?.data?.update;
                         if (update?.sessionUpdate === "tool_call") {
+                            // Deduplicate phased tool_call events by toolCallId
+                            const toolCallId = update?.toolCallId || update?.tool_call_id || update?.id;
+                            if (toolCallId && seenToolCallIds.has(toolCallId))
+                                continue;
+                            if (toolCallId)
+                                seenToolCallIds.add(toolCallId);
                             const toolName = update?._meta?.claudeCode?.toolName || "unknown";
                             toolCounts[toolName] = (toolCounts[toolName] || 0) + 1;
                             totalToolCalls++;
@@ -880,6 +1147,8 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
             continue;
         const matches = [];
         const lines = content.trim().split("\n");
+        // Track seen tool_call IDs to skip phased duplicates
+        const seenToolCallIds = new Set();
         for (const line of lines) {
             if (totalMatches >= limit)
                 break;
@@ -891,6 +1160,18 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
                 // AC: @session-log-search ac-2 - Filter by event type
                 if (options.eventType && event.type !== options.eventType)
                     continue;
+                // Deduplicate phased tool_call events
+                if (event?.type === "session.update") {
+                    const update = event?.data?.update;
+                    if (update?.sessionUpdate === "tool_call") {
+                        const toolCallId = update?.toolCallId || update?.tool_call_id || update?.id;
+                        if (toolCallId) {
+                            if (seenToolCallIds.has(toolCallId))
+                                continue;
+                            seenToolCallIds.add(toolCallId);
+                        }
+                    }
+                }
                 // Verify match in stringified data (not just line, in case pattern appears in metadata)
                 const dataStr = JSON.stringify(event.data);
                 if (!dataStr.toLowerCase().includes(lowerPattern))
@@ -919,4 +1200,397 @@ export async function searchSessionEvents(specDir, pattern, options = {}) {
     }
     return results;
 }
+// ─── Session Creation with Budget ─────────────────────────────────────────────
+/**
+ * Create a session with an optional task budget in one call.
+ *
+ * This is the library-level entry point for session creation. It creates
+ * the session directory, writes session.yaml, and optionally writes budget.json.
+ * Returns metadata without any console output.
+ *
+ * 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-library
+ *
+ * @param specDir - The .kspec directory path
+ * @param input - Session creation parameters
+ * @returns Session metadata and optional budget (no console output)
+ */
+export async function createSessionWithBudget(specDir, input) {
+    // Create session
+    const session = await createSession(specDir, {
+        id: input.id,
+        agent_type: input.agent_type,
+        task_id: input.task_id,
+    });
+    // Optionally create budget
+    let budget = null;
+    if (input.budget !== undefined && input.budget > 0) {
+        budget = await createBudget(specDir, input.id, input.budget);
+    }
+    return {
+        session_id: input.id,
+        session,
+        budget,
+    };
+}
+/**
+ * Write or update KSPEC_SESSION_ID in a dotenv-style file.
+ * Replaces an existing KSPEC_SESSION_ID line or appends a new one.
+ */
+async function upsertDotenvSessionId(filePath, sessionId) {
+    let content = "";
+    try {
+        content = await fsPromises.readFile(filePath, "utf-8");
+    }
+    catch (err) {
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist yet, start fresh
+        }
+        else {
+            throw err;
+        }
+    }
+    const lines = content.split("\n");
+    const existingIdx = lines.findIndex((l) => l.startsWith("KSPEC_SESSION_ID="));
+    if (existingIdx >= 0) {
+        lines[existingIdx] = `KSPEC_SESSION_ID=${sessionId}`;
+    }
+    else {
+        // Append before final empty line if present
+        if (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines.splice(lines.length - 1, 0, `KSPEC_SESSION_ID=${sessionId}`);
+        }
+        else {
+            lines.push(`KSPEC_SESSION_ID=${sessionId}`);
+        }
+    }
+    await fsPromises.writeFile(filePath, lines.join("\n"), "utf-8");
+}
+/**
+ * Inject KSPEC_SESSION_ID into Claude Code environment.
+ *
+ * Strategy:
+ * 1. If CLAUDE_ENV_FILE is set, write to that file
+ * 2. Otherwise, append to project .claude/settings.json env section
+ *
+ * AC: @session-creation-and-env-injection ac-inject-claude
+ */
+export async function injectClaudeCodeEnv(sessionId) {
+    const envFile = process.env.CLAUDE_ENV_FILE;
+    if (envFile) {
+        await upsertDotenvSessionId(envFile, sessionId);
+        return {
+            injected: true,
+            method: "claude_env_file",
+            description: `Wrote KSPEC_SESSION_ID=${sessionId} to CLAUDE_ENV_FILE`,
+            path: envFile,
+        };
+    }
+    // Fallback: write to project .claude/settings.json
+    const settingsDir = path.join(process.cwd(), ".claude");
+    const settingsPath = path.join(settingsDir, "settings.json");
+    await fsPromises.mkdir(settingsDir, { recursive: true });
+    let settings = {};
+    try {
+        const content = await fsPromises.readFile(settingsPath, "utf-8");
+        settings = JSON.parse(content);
+    }
+    catch (err) {
+        // Only start fresh for ENOENT; throw on parse errors to avoid overwriting
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist, start fresh
+        }
+        else {
+            throw new Error(`Cannot inject env: .claude/settings.json exists but is not valid JSON. ` +
+                `Fix the file manually or remove it, then retry.`);
+        }
+    }
+    // Ensure env section exists
+    if (!settings.env || typeof settings.env !== "object") {
+        settings.env = {};
+    }
+    settings.env.KSPEC_SESSION_ID = sessionId;
+    await fsPromises.writeFile(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return {
+        injected: true,
+        method: "claude_settings",
+        description: `Added KSPEC_SESSION_ID to .claude/settings.json env section`,
+        path: settingsPath,
+    };
+}
+/**
+ * Inject KSPEC_SESSION_ID into Codex CLI environment.
+ *
+ * Adds to shell_environment_policy.set in codex config.
+ *
+ * AC: @session-creation-and-env-injection ac-inject-codex
+ */
+export async function injectCodexEnv(sessionId) {
+    const configDir = path.join(process.env.HOME || process.env.USERPROFILE || "", ".codex");
+    const configPath = path.join(configDir, "config.json");
+    await fsPromises.mkdir(configDir, { recursive: true });
+    let config = {};
+    try {
+        const content = await fsPromises.readFile(configPath, "utf-8");
+        config = JSON.parse(content);
+    }
+    catch (err) {
+        // Only start fresh for ENOENT; throw on parse errors to avoid overwriting
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            // File doesn't exist, start fresh
+        }
+        else {
+            throw new Error(`Cannot inject env: ~/.codex/config.json exists but is not valid JSON. ` +
+                `Fix the file manually or remove it, then retry.`);
+        }
+    }
+    // Ensure shell_environment_policy.set exists
+    if (!config.shell_environment_policy ||
+        typeof config.shell_environment_policy !== "object") {
+        config.shell_environment_policy = {};
+    }
+    const policy = config.shell_environment_policy;
+    if (!policy.set || typeof policy.set !== "object") {
+        policy.set = {};
+    }
+    policy.set.KSPEC_SESSION_ID = sessionId;
+    await fsPromises.writeFile(configPath, JSON.stringify(config, null, 2) + "\n", "utf-8");
+    return {
+        injected: true,
+        method: "codex_config",
+        description: `Added KSPEC_SESSION_ID to Codex config shell_environment_policy.set`,
+        path: configPath,
+    };
+}
+/**
+ * Inject KSPEC_SESSION_ID into Gemini CLI environment.
+ *
+ * Writes to .gemini/.env in project root (auto-loaded by Gemini CLI).
+ */
+export async function injectGeminiEnv(sessionId) {
+    const dotenvDir = path.join(process.cwd(), ".gemini");
+    const dotenvPath = path.join(dotenvDir, ".env");
+    await fsPromises.mkdir(dotenvDir, { recursive: true });
+    await upsertDotenvSessionId(dotenvPath, sessionId);
+    return {
+        injected: true,
+        method: "gemini_dotenv",
+        description: `Wrote KSPEC_SESSION_ID=${sessionId} to .gemini/.env`,
+        path: dotenvPath,
+    };
+}
+/**
+ * Inject KSPEC_SESSION_ID into OpenCode environment.
+ *
+ * Writes to project root .env file (auto-loaded by OpenCode via Bun runtime).
+ * Uses the same dotenv append/replace pattern as other injectors.
+ */
+export async function injectOpenCodeEnv(sessionId) {
+    const dotenvPath = path.join(process.cwd(), ".env");
+    await upsertDotenvSessionId(dotenvPath, sessionId);
+    return {
+        injected: true,
+        method: "opencode_dotenv",
+        description: `Wrote KSPEC_SESSION_ID=${sessionId} to .env`,
+        path: dotenvPath,
+    };
+}
+/**
+ * Get fallback injection instructions for unknown agent harnesses.
+ *
+ * AC: @session-creation-and-env-injection ac-inject-fallback
+ */
+export function getFallbackInjectionInstructions(sessionId) {
+    return {
+        injected: false,
+        method: "fallback",
+        description: `export KSPEC_SESSION_ID=${sessionId}`,
+    };
+}
+// ─── Session Validation ───────────────────────────────────────────────────────
+/**
+ * Validate that the current KSPEC_SESSION_ID points to a valid session.
+ *
+ * AC: @session-creation-and-env-injection ac-invalid-session
+ *
+ * @param specDir - 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) {
+    // Check if session directory exists
+    const exists = await sessionExists(specDir, sessionId);
+    if (!exists) {
+        return {
+            valid: false,
+            error: `Session not found: ${sessionId}`,
+            suggestion: `Unset KSPEC_SESSION_ID or create a new session with: kspec session create --agent-type <type>`,
+        };
+    }
+    // Try to read and validate session metadata
+    const session = await getSession(specDir, sessionId);
+    if (!session) {
+        return {
+            valid: false,
+            error: `Session metadata is corrupt or unreadable: ${sessionId}`,
+            suggestion: `Unset KSPEC_SESSION_ID or create a new session with: kspec session create --agent-type <type>`,
+        };
+    }
+    return { valid: true, session };
+}
+// ─── Task Budget ──────────────────────────────────────────────────────────────
+/**
+ * Atomic JSON write — write to temp file then rename in same directory.
+ * Prevents corruption on crash.
+ * AC: @task-budget-enforcement ac-atomic-write
+ */
+async function writeBudgetAtomic(filePath, budget) {
+    const dir = path.dirname(filePath);
+    await fsPromises.mkdir(dir, { recursive: true });
+    const tmpPath = `${filePath}.${process.pid}.tmp`;
+    const content = JSON.stringify(budget, null, 2) + "\n";
+    await fsPromises.writeFile(tmpPath, content, "utf-8");
+    await fsPromises.rename(tmpPath, filePath);
+}
+/**
+ * Create a budget for a session.
+ *
+ * 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 sessionId - Session ID
+ * @param maxPerCycle - Maximum tasks allowed per cycle
+ * @returns The created budget
+ */
+export async function createBudget(specDir, sessionId, maxPerCycle) {
+    const budget = {
+        max_per_cycle: maxPerCycle,
+        started_this_cycle: 0,
+    };
+    const validated = TaskBudgetSchema.parse(budget);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
+/**
+ * Read budget for a session.
+ *
+ * AC: @task-budget-enforcement ac-no-budget
+ *
+ * @param specDir - 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);
+    let content;
+    try {
+        content = await fsPromises.readFile(budgetPath, "utf-8");
+    }
+    catch (err) {
+        // File doesn't exist = no budget configured (opt-in)
+        if (err instanceof Error && "code" in err && err.code === "ENOENT") {
+            return null;
+        }
+        throw err;
+    }
+    // File exists — parse errors are real failures, not "no budget"
+    const raw = JSON.parse(content);
+    return TaskBudgetSchema.parse(raw);
+}
+/**
+ * Check whether the budget allows starting a new task.
+ *
+ * Returns an object with `allowed` boolean and context about the budget.
+ * When no budget is configured, always allows (opt-in behavior).
+ *
+ * AC: @task-budget-enforcement ac-block-start
+ * AC: @task-budget-enforcement ac-no-budget
+ * AC: @task-budget-enforcement ac-no-session
+ *
+ * @param specDir - 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) {
+    // AC: @task-budget-enforcement ac-no-session — no session means no check
+    if (!sessionId) {
+        return { allowed: true };
+    }
+    const budget = await getBudget(specDir, sessionId);
+    // AC: @task-budget-enforcement ac-no-budget — no budget means no check
+    if (!budget) {
+        return { allowed: true };
+    }
+    if (budget.started_this_cycle >= budget.max_per_cycle) {
+        return {
+            allowed: false,
+            reason: `Task budget exhausted: ${budget.started_this_cycle}/${budget.max_per_cycle} tasks started this cycle. Wrap up current work and let the iteration end naturally without starting new tasks.`,
+            budget,
+        };
+    }
+    return { allowed: true, budget };
+}
+/**
+ * Increment the budget counter after a task is successfully started.
+ *
+ * IMPORTANT: Callers must NOT call this for resume cases (task already
+ * in_progress). The budget should only be incremented when a new task
+ * transitions to in_progress, not when resuming an existing one.
+ * See AC: @task-budget-enforcement ac-resume-no-increment
+ *
+ * AC: @task-budget-enforcement ac-increment
+ * AC: @task-budget-enforcement ac-atomic-write
+ *
+ * @param specDir - 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);
+    if (!budget) {
+        return null;
+    }
+    const updated = {
+        ...budget,
+        started_this_cycle: budget.started_this_cycle + 1,
+    };
+    const validated = TaskBudgetSchema.parse(updated);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
+/**
+ * Reset the budget counter to 0 for a new cycle/iteration.
+ *
+ * Called by ralph at iteration boundaries. Single-writer guarantee:
+ * ralph only resets between iterations when the agent is not running.
+ *
+ * AC: @task-budget-enforcement ac-reset
+ * AC: @task-budget-enforcement ac-atomic-write
+ *
+ * @param specDir - 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);
+    if (!budget) {
+        return null;
+    }
+    const updated = {
+        ...budget,
+        started_this_cycle: 0,
+    };
+    const validated = TaskBudgetSchema.parse(updated);
+    const budgetPath = getSessionBudgetPath(specDir, sessionId);
+    await writeBudgetAtomic(budgetPath, validated);
+    return validated;
+}
 //# sourceMappingURL=store.js.map