@kynetic-ai/spec 0.4.0 → 0.6.0

package/dist/cli/commands/ralph.js

@@ -17,185 +17,12 @@ import { registerAdapter, resolveAdapter, } from "../../agents/index.js";
 import { spawnAndInitialize } from "../../agents/spawner.js";
 import { initContext, loadAllItems, loadAllTasks, ReferenceIndex, } from "../../parser/index.js";
 import { buildWrapUpContext, createCliRenderer, createTranslator, DEFAULT_SUBAGENT_PREFIX, DEFAULT_WRAPUP_TIMEOUT, RALPH_PROMPT_TIMEOUT, runSubagent, runWrapUpAgent, WRAPUP_AGENT_PREFIX, } from "../../ralph/index.js";
-import { appendEvent, createSession, saveSessionContext, updateSessionStatus, } from "../../sessions/index.js";
+import { appendEvent, closeSession, createSessionWithBudget, getSessionBudgetPath, injectEnvForAdapter, isEndLoopRequested, removeEnvForAdapter, requestEndLoop, resetBudget, saveSessionContext, } from "../../sessions/index.js";
 import { errors } from "../../strings/index.js";
 import { getCurrentBranch } from "../../utils/git.js";
 import { EXIT_CODES } from "../exit-codes.js";
 import { error, info, success, warn } from "../output.js";
-import { gatherSessionContext, getIterationStats, } from "./session.js";
-const TASK_LIMIT_MARKER_PATH = ".claude/ralph-task-limit.json";
-const END_LOOP_MARKER_PATH = ".claude/ralph-end-loop.json";
-const STALE_MARKER_THRESHOLD_MS = 60 * 60 * 1000; // 1 hour
-/**
- * Write task limit marker file.
- * AC: @ralph-task-limit ac-wrapup, ac-marker-format
- */
-async function writeTaskLimitMarker(rootDir, marker) {
-    const markerPath = path.join(rootDir, TASK_LIMIT_MARKER_PATH);
-    const dir = path.dirname(markerPath);
-    await fs.mkdir(dir, { recursive: true });
-    await fs.writeFile(markerPath, JSON.stringify(marker, null, 2));
-}
-/**
- * Read task limit marker file if it exists.
- */
-async function readTaskLimitMarker(rootDir) {
-    const markerPath = path.join(rootDir, TASK_LIMIT_MARKER_PATH);
-    try {
-        const content = await fs.readFile(markerPath, "utf-8");
-        return JSON.parse(content);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Clear task limit marker file.
- * AC: @ralph-task-limit ac-reset
- */
-async function clearTaskLimitMarker(rootDir) {
-    const markerPath = path.join(rootDir, TASK_LIMIT_MARKER_PATH);
-    try {
-        await fs.unlink(markerPath);
-    }
-    catch {
-        // Ignore if file doesn't exist
-    }
-}
-/**
- * Clear stale marker files (older than 1 hour).
- * AC: @ralph-task-limit ac-reset
- */
-async function clearStaleMarker(rootDir) {
-    const marker = await readTaskLimitMarker(rootDir);
-    if (!marker)
-        return false;
-    const markerAge = Date.now() - new Date(marker.since).getTime();
-    if (markerAge > STALE_MARKER_THRESHOLD_MS) {
-        await clearTaskLimitMarker(rootDir);
-        return true;
-    }
-    return false;
-}
-/**
- * Write end-loop marker file.
- * AC: @ralph-end-loop ac-cmd
- */
-async function writeEndLoopMarker(rootDir, reason) {
-    const markerPath = path.join(rootDir, END_LOOP_MARKER_PATH);
-    const dir = path.dirname(markerPath);
-    await fs.mkdir(dir, { recursive: true });
-    const marker = {
-        requested: true,
-        timestamp: new Date().toISOString(),
-        reason,
-    };
-    await fs.writeFile(markerPath, JSON.stringify(marker, null, 2));
-}
-/**
- * Read end-loop marker file if it exists.
- * AC: @ralph-end-loop ac-detect
- */
-async function readEndLoopMarker(rootDir) {
-    const markerPath = path.join(rootDir, END_LOOP_MARKER_PATH);
-    try {
-        const content = await fs.readFile(markerPath, "utf-8");
-        return JSON.parse(content);
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Clear end-loop marker file.
- * AC: @ralph-end-loop ac-cleanup
- */
-async function clearEndLoopMarker(rootDir) {
-    const markerPath = path.join(rootDir, END_LOOP_MARKER_PATH);
-    try {
-        await fs.unlink(markerPath);
-    }
-    catch {
-        // Ignore if file doesn't exist
-    }
-}
-/**
- * Clear stale end-loop markers (older than 1 hour).
- * AC: @ralph-end-loop ac-cleanup
- */
-async function clearStaleEndLoopMarker(rootDir) {
-    const marker = await readEndLoopMarker(rootDir);
-    if (!marker)
-        return false;
-    const markerAge = Date.now() - new Date(marker.timestamp).getTime();
-    if (markerAge > STALE_MARKER_THRESHOLD_MS) {
-        await clearEndLoopMarker(rootDir);
-        return true;
-    }
-    return false;
-}
-/**
- * Detect if a Bash command is a task complete command.
- * AC: @ralph-task-limit ac-detection
- */
-function detectTaskCompleteCommand(command) {
-    // Match variations of "kspec task complete"
-    // Don't match "kspec task submit" - that's just status change to pending_review
-    return /\bkspec\s+task\s+complete\b/.test(command);
-}
-/**
- * Detect if a Bash command is an end-loop command.
- * AC: @ralph-end-loop ac-detect
- */
-function detectEndLoopCommand(command) {
-    // Match "kspec ralph end-loop" with any arguments
-    return /\bkspec\s+ralph\s+end-loop\b/.test(command);
-}
-/**
- * Extract Bash command from SessionUpdate if it's a tool_call or tool_call_update event.
- * Returns null if not a Bash tool call.
- */
-function extractBashCommand(update) {
-    const u = update;
-    // Check if this is a tool call event
-    if (u.sessionUpdate !== "tool_call" && u.sessionUpdate !== "tool_call_update") {
-        return null;
-    }
-    // Extract tool name - check various locations Claude Code uses
-    let toolName;
-    // Try _meta.claudeCode.toolName first (Claude Code pattern)
-    const meta = u._meta;
-    if (meta) {
-        const claudeCode = meta.claudeCode;
-        if (claudeCode?.toolName) {
-            toolName = String(claudeCode.toolName);
-        }
-        else if (meta.toolName) {
-            toolName = String(meta.toolName);
-        }
-    }
-    // Fall back to name or title field
-    if (!toolName && u.name) {
-        toolName = String(u.name);
-    }
-    if (!toolName && u.title) {
-        toolName = String(u.title);
-    }
-    // Check if it's a Bash tool (handle MCP prefix variations)
-    if (!toolName)
-        return null;
-    const isBash = toolName === "Bash" || toolName.endsWith("__Bash");
-    if (!isBash)
-        return null;
-    // Extract command from input
-    const input = (u.rawInput || u.input || u.params);
-    if (!input)
-        return null;
-    const command = input.command;
-    if (typeof command !== "string")
-        return null;
-    return command;
-}
+import { gatherSessionContext, } from "./session.js";
 /**
  * Parse and validate --tasks flag value.
  * Returns resolved ULIDs for the specified task refs.
@@ -735,7 +562,7 @@ export function registerRalphCommand(program) {
         .command("ralph")
         .description("Ralph automated task loop and agent control");
     // end-loop subcommand - allows agent to signal loop termination
-    // AC: @ralph-end-loop ac-cmd, ac-reason, ac-noop-outside
+    // AC: @session-end-loop-signal ac-signal
     ralph
         .command("end-loop")
         .description("End the ralph loop gracefully (stops all remaining iterations)")
@@ -743,26 +570,31 @@ export function registerRalphCommand(program) {
         .action(async (options) => {
         try {
             const ctx = await initContext();
-            // Check if we're in a ralph session by looking for any ralph marker
-            const taskLimitMarker = await readTaskLimitMarker(ctx.rootDir);
-            const endLoopMarker = await readEndLoopMarker(ctx.rootDir);
-            // Write the marker with reason if provided
-            await writeEndLoopMarker(ctx.rootDir, options.reason);
-            // Determine if we're likely in a ralph session
-            const inRalphSession = taskLimitMarker !== null || endLoopMarker !== null;
-            if (!inRalphSession) {
-                // AC: @ralph-end-loop ac-noop-outside
-                warn("No active ralph session detected. Marker written but may have no effect.");
-                info("This command is designed to be called by agents during a ralph loop.");
+            const sessionId = process.env.KSPEC_SESSION_ID;
+            if (!sessionId) {
+                // AC: @trait-error-guidance ac-1, ac-2
+                warn("No active ralph session detected (KSPEC_SESSION_ID not set).");
+                info("This command requires an active session. It is designed to be called by agents during a ralph loop.");
+                info("Suggestion: Ensure KSPEC_SESSION_ID is set, or start a session with: kspec session create --agent-type ralph");
+                process.exit(EXIT_CODES.VALIDATION_FAILED);
+                return;
             }
-            else {
-                success("Loop end signal sent");
+            // AC: @session-end-loop-signal ac-signal - Write end-loop state to session
+            const updated = await requestEndLoop(ctx.specDir, sessionId, options.reason);
+            if (!updated) {
+                // AC: @trait-error-guidance ac-1, ac-2
+                error(`Session not found: ${sessionId}`);
+                info("Suggestion: Check session ID with: kspec session log list");
+                process.exit(EXIT_CODES.NOT_FOUND);
+                return;
             }
+            success("Loop end signal sent");
             if (options.reason) {
                 info(`Reason: ${options.reason}`);
             }
         }
         catch (err) {
+            // AC: @trait-error-guidance ac-1
             error("Failed to signal end-loop", err);
             process.exit(EXIT_CODES.ERROR);
         }
@@ -830,7 +662,7 @@ export function registerRalphCommand(program) {
                 error("--restart-every must be a non-negative integer");
                 process.exit(EXIT_CODES.ERROR);
             }
-            // AC: @ralph-task-limit ac-flag
+            // AC: @ralph-session-budget-integration ac-create-budget
             const maxTasks = parseInt(options.maxTasks, 10);
             if (Number.isNaN(maxTasks) || maxTasks < 0 || maxTasks > 999) {
                 error("--max-tasks must be 0 (unlimited) or a positive integer up to 999");
@@ -895,91 +727,108 @@ export function registerRalphCommand(program) {
             const specDir = ctx.specDir;
             // Create session for event tracking
             const sessionId = ulid();
-            await createSession(specDir, {
+            // Set session env vars on this process so all spawned agents
+            // (main worker, subagent, wrap-up) inherit them via process.env.
+            // KSPEC_RALPH_SESSION: Used by codex skill safety guard to detect ralph context.
+            // KSPEC_SESSION_ID: Used by kspec task start for budget enforcement.
+            // AC: @ralph-session-budget-integration ac-env-inject
+            process.env.KSPEC_RALPH_SESSION = sessionId;
+            process.env.KSPEC_SESSION_ID = sessionId;
+            // AC: @ralph-session-budget-integration ac-create-budget
+            // Create session with budget. When maxTasks=0 (unlimited), no budget.json is created.
+            await createSessionWithBudget(specDir, {
                 id: sessionId,
                 agent_type: options.adapter,
-                task_id: undefined, // Will be determined per iteration
-            });
-            // Log session start
-            await appendEvent(specDir, {
-                session_id: sessionId,
-                type: "session.start",
-                data: {
-                    adapter: options.adapter,
-                    maxLoops,
-                    maxRetries,
-                    maxFailures,
-                    maxTasks,
-                    yolo: options.yolo,
-                    focus: options.focus,
-                    explicitTasks: explicitTaskScope?.refs,
-                },
+                budget: maxTasks,
             });
+            // Adapter ID for harness-specific env injection/cleanup.
+            // Declared before try/finally so signal handlers and finally block can access it.
+            const adapterId = options.adapter || "claude-agent-acp";
+            // Everything after session creation is wrapped in try/finally to guarantee
+            // budget cleanup even if pre-loop setup (event logging, signal handlers) throws.
+            // AC: @ralph-session-budget-integration ac-session-close-all-paths
             let consecutiveFailures = 0;
             let agent = null;
             let acpSessionId = null;
-            // AC: @ralph-end-loop ac-signal-cleanup, @ralph-task-limit ac-signal-cleanup
-            // Signal handlers for cleanup on Ctrl+C or kill
-            // Note: Signal handlers must be synchronous, so we use Promise.finally()
-            // to ensure cleanup completes before exit
+            let exitReason = null;
+            let lastIterationCtx = null;
+            let lastErrorMessage;
+            let previousEnvValue; // For restoring pre-existing KSPEC_SESSION_ID
+            const recentTaskRefs = [];
+            const sessionIterationMap = new Map();
+            // Signal handler refs — declared here so finally can remove them
+            // AC: @ralph-task-limit ac-signal-cleanup
             const signalCleanup = (signal) => {
                 info(`Received ${signal}, cleaning up...`);
-                // Kill agent if running
                 if (agent) {
                     agent.kill();
                 }
-                // Clean up marker files, then exit after cleanup completes
-                Promise.all([
-                    clearTaskLimitMarker(ctx.rootDir),
-                    clearEndLoopMarker(ctx.rootDir),
-                ]).finally(() => {
-                    process.exit(0);
-                });
+                // AC: @ralph-session-budget-integration ac-session-close-all-paths
+                // Must use async IIFE — signal handlers are called synchronously,
+                // but cleanup needs async I/O. The IIFE keeps the event loop alive
+                // until cleanup completes, then exits explicitly.
+                void (async () => {
+                    try {
+                        await Promise.all([
+                            fs.unlink(getSessionBudgetPath(specDir, sessionId)).catch(() => { }),
+                            closeSession(specDir, sessionId, "abandoned", `Received ${signal}`),
+                            removeEnvForAdapter(adapterId, previousEnvValue),
+                        ]);
+                    }
+                    catch {
+                        // Best-effort cleanup — don't let errors prevent exit
+                    }
+                    finally {
+                        process.exit(0);
+                    }
+                })();
             };
             const sigintHandler = () => { signalCleanup("SIGINT"); };
             const sigtermHandler = () => { signalCleanup("SIGTERM"); };
-            process.on("SIGINT", sigintHandler);
-            process.on("SIGTERM", sigtermHandler);
-            // Create translator and renderer for this session
-            const translator = createTranslator();
-            const renderer = createCliRenderer();
-            // Task limit state - tracks completions per iteration
-            // AC: @ralph-task-limit ac-reset, ac-wrapup
-            let taskLimitReached = false;
-            let tasksCompletedThisIteration = 0;
-            // End-loop signal state
-            // AC: @ralph-end-loop ac-detect, ac-graceful
-            let endLoopRequested = false;
-            // AC: @ralph-wrap-up-agent-on-loop-exit ac-1 - Track exit reason for wrap-up
-            let exitReason = null;
-            let lastIterationCtx = null;
-            let lastErrorMessage;
-            const recentTaskRefs = [];
-            // Map ACP session IDs to their iteration number.
-            // The agent's "update" handler persists across iterations and receives
-            // the ACP session ID (_sid) on each event. By looking up the iteration
-            // from this map, late updates from a previous ACP session are correctly
-            // attributed even after the loop has advanced to the next iteration.
-            const sessionIterationMap = new Map();
             try {
+                // AC: @session-end-loop-signal ac-session-close-signal
+                // Install signal handlers FIRST, before any async work, so signals
+                // during startup (e.g. during appendEvent) still trigger cleanup.
+                // AC: @ralph-session-budget-integration ac-session-close-all-paths
+                process.on("SIGINT", sigintHandler);
+                process.on("SIGTERM", sigtermHandler);
+                // Inject KSPEC_SESSION_ID into agent harness config so it reaches child
+                // processes. Inside try/finally so cleanup runs even if injection fails.
+                // Process env alone is insufficient — some harnesses (e.g., Claude Code)
+                // sandbox child processes and don't forward arbitrary parent env vars.
+                // AC: @ralph-session-budget-integration ac-env-inject
+                const injectionResult = await injectEnvForAdapter(adapterId, sessionId);
+                previousEnvValue = injectionResult?.previousValue;
+                // Log session start
+                await appendEvent(specDir, {
+                    session_id: sessionId,
+                    type: "session.start",
+                    data: {
+                        adapter: options.adapter,
+                        maxLoops,
+                        maxRetries,
+                        maxFailures,
+                        maxTasks,
+                        yolo: options.yolo,
+                        focus: options.focus,
+                        explicitTasks: explicitTaskScope?.refs,
+                    },
+                });
+                // Create translator and renderer for this session
+                const translator = createTranslator();
+                const renderer = createCliRenderer();
                 for (let iteration = 1; iteration <= maxLoops; iteration++) {
                     renderer.newSection?.(`Iteration ${iteration}/${maxLoops}`);
-                    // AC: @ralph-task-limit ac-reset - Reset counter and clear stale markers at iteration start
-                    taskLimitReached = false;
-                    tasksCompletedThisIteration = 0;
-                    const wasStale = await clearStaleMarker(ctx.rootDir);
-                    if (wasStale) {
-                        info("Cleared stale task limit marker from previous session");
-                    }
-                    // Also clear any marker from previous iteration of this session
-                    await clearTaskLimitMarker(ctx.rootDir);
-                    // AC: @ralph-end-loop ac-cleanup - Reset end-loop state
-                    endLoopRequested = false;
-                    const wasStaleEndLoop = await clearStaleEndLoopMarker(ctx.rootDir);
-                    if (wasStaleEndLoop) {
-                        info("Cleared stale end-loop marker from previous session");
+                    // AC: @ralph-session-budget-integration ac-reset-iteration
+                    // Reset budget counter at iteration start (no-op when no budget exists)
+                    await resetBudget(specDir, sessionId);
+                    // AC: @session-end-loop-signal ac-detect - Check session state for end-loop
+                    const endLoopState = await isEndLoopRequested(specDir, sessionId);
+                    if (endLoopState?.requested) {
+                        info(`End-loop already requested for this session. Exiting.`);
+                        exitReason = "end_loop_signal";
+                        break;
                     }
-                    await clearEndLoopMarker(ctx.rootDir);
                     // Gather fresh context each iteration
                     // AC: @cli-ralph ac-16 - Only automation-eligible tasks (unless explicit scope)
                     // AC: @cli-ralph ac-21 - With explicit task scope, ignore automation eligibility
@@ -1055,7 +904,7 @@ export function registerRalphCommand(program) {
                     // AC: @cli-ralph ac-21 - Include explicit task scope in prompt
                     const taskWorkPrompt = buildTaskWorkPrompt(currentCtx, iteration, maxLoops, sessionId, ctx.config.ralph.skills.task_work, options.focus, explicitTaskScope);
                     const reflectPrompt = buildReflectPrompt(iteration, maxLoops, sessionId, ctx.config.ralph.skills.reflect);
-                    // AC: @ralph-task-limit ac-dryrun, @cli-ralph ac-21
+                    // AC: @cli-ralph ac-21
                     if (options.dryRun) {
                         console.log(chalk.yellow("=== DRY RUN - Configuration ===\n"));
                         console.log(`  max-loops: ${maxLoops}`);
@@ -1098,8 +947,10 @@ export function registerRalphCommand(program) {
                             // Spawn agent if not already running
                             if (!agent) {
                                 info("Spawning ACP agent...");
+                                // AC: @ralph-session-budget-integration ac-env-inject
                                 agent = await spawnAndInitialize(adapter, {
                                     cwd: process.cwd(),
+                                    env: { KSPEC_SESSION_ID: sessionId },
                                     clientOptions: {
                                         clientInfo: {
                                             name: "kspec-ralph",
@@ -1118,64 +969,6 @@ export function registerRalphCommand(program) {
                                     if (event) {
                                         renderer.render(event);
                                     }
-                                    // AC: @ralph-task-limit ac-detection, ac-wrapup
-                                    // Detect task completions for limit enforcement
-                                    if (maxTasks > 0 && !taskLimitReached) {
-                                        const bashCmd = extractBashCommand(update);
-                                        if (bashCmd && detectTaskCompleteCommand(bashCmd)) {
-                                            // Pattern matched - verify via kspec query
-                                            getIterationStats(ctx, iterationStartTime)
-                                                .then(async (stats) => {
-                                                if (stats.tasks_completed >= maxTasks && !taskLimitReached) {
-                                                    taskLimitReached = true;
-                                                    tasksCompletedThisIteration = stats.tasks_completed;
-                                                    info(`Task limit reached (${stats.tasks_completed}/${maxTasks})`);
-                                                    // AC: @ralph-task-limit ac-marker-format, ac-wrapup
-                                                    // Write marker file for hook enforcement
-                                                    const marker = {
-                                                        active: true,
-                                                        since: iterationStartTime.toISOString(),
-                                                        max: maxTasks,
-                                                        completed: stats.tasks_completed,
-                                                        sessionId,
-                                                    };
-                                                    await writeTaskLimitMarker(ctx.rootDir, marker);
-                                                    // Inject wrap-up message to agent
-                                                    if (agent && acpSessionId) {
-                                                        const wrapUpMsg = `\n\n**TASK LIMIT REACHED** - ${stats.tasks_completed} task(s) completed this iteration (limit: ${maxTasks}).\n\nPlease wrap up your current work and exit cleanly. Do not start new tasks.\n\nCompleted tasks this iteration: ${stats.completed_refs.join(", ")}`;
-                                                        agent.client.prompt({
-                                                            sessionId: acpSessionId,
-                                                            prompt: [{ type: "text", text: wrapUpMsg }],
-                                                        }).catch(() => {
-                                                            // Ignore if message injection fails
-                                                        });
-                                                    }
-                                                }
-                                            })
-                                                .catch(() => {
-                                                // Ignore query failures - detection is best-effort
-                                            });
-                                        }
-                                    }
-                                    // AC: @ralph-end-loop ac-detect
-                                    // Detect explicit end-loop command
-                                    if (!endLoopRequested) {
-                                        const bashCmd = extractBashCommand(update);
-                                        if (bashCmd && detectEndLoopCommand(bashCmd)) {
-                                            endLoopRequested = true;
-                                            // Read marker to get reason if present
-                                            readEndLoopMarker(ctx.rootDir)
-                                                .then((marker) => {
-                                                const reason = marker?.reason
-                                                    ? ` (${marker.reason})`
-                                                    : "";
-                                                info(`End-loop signal received${reason}`);
-                                            })
-                                                .catch(() => {
-                                                info("End-loop signal received");
-                                            });
-                                        }
-                                    }
                                     // Log raw update event (async, non-blocking)
                                     // Look up iteration by ACP session ID so late updates from
                                     // a previous session are attributed to the correct iteration
@@ -1280,12 +1073,6 @@ export function registerRalphCommand(program) {
                             }
                         }
                         lastIterationCtx = sessionCtx;
-                        // AC: @ralph-end-loop ac-graceful - Check for end-loop signal
-                        if (endLoopRequested) {
-                            info("Agent requested end of loop. Exiting gracefully.");
-                            exitReason = "end_loop_signal";
-                            break;
-                        }
                         // Periodic agent restart to prevent OOM
                         // AC: @cli-ralph ac-restart-periodic
                         if (restartEvery > 0 &&
@@ -1323,6 +1110,13 @@ export function registerRalphCommand(program) {
                     exitReason = "max_iterations";
                 }
             }
+            catch (loopErr) {
+                // AC: @session-end-loop-signal ac-session-close-error
+                // Unrecoverable error during loop execution
+                exitReason = exitReason ?? "error";
+                lastErrorMessage = loopErr.message;
+                error("Unrecoverable error in ralph loop", loopErr);
+            }
             finally {
                 // Remove signal handlers to avoid double cleanup
                 process.off("SIGINT", sigintHandler);
@@ -1332,10 +1126,13 @@ export function registerRalphCommand(program) {
                     agent.kill();
                     agent = null;
                 }
-                // AC: @ralph-task-limit ac-reset - Clear marker file when session ends
-                await clearTaskLimitMarker(ctx.rootDir);
-                // AC: @ralph-end-loop ac-cleanup - Clear end-loop marker when session ends
-                await clearEndLoopMarker(ctx.rootDir);
+                // AC: @ralph-session-budget-integration ac-session-close-all-paths
+                // Clean up budget file and harness env injection when session ends
+                await fs.unlink(getSessionBudgetPath(specDir, sessionId)).catch(() => { });
+                await removeEnvForAdapter(adapterId, previousEnvValue);
+                // Clean up session env vars
+                delete process.env.KSPEC_RALPH_SESSION;
+                delete process.env.KSPEC_SESSION_ID;
                 // AC: @ralph-wrap-up-agent-on-loop-exit ac-1, ac-2, ac-3, ac-4, ac-5
                 // Spawn wrap-up agent if not dry-run and we have an exit reason
                 if (!options.dryRun && exitReason) {
@@ -1382,8 +1179,25 @@ export function registerRalphCommand(program) {
                     console.log(chalk.cyan(`${"═".repeat(60)}`));
                     console.log("");
                 }
-                // Log session end
-                const status = consecutiveFailures >= maxFailures ? "abandoned" : "completed";
+                // Log session end and close session with appropriate status/reason
+                // AC: @session-end-loop-signal ac-session-close-normal, ac-session-close-error
+                const isErrorExit = consecutiveFailures >= maxFailures ||
+                    exitReason === "max_failures" ||
+                    exitReason === "error";
+                const status = isErrorExit ? "abandoned" : "completed";
+                const closeReason = exitReason === "max_failures"
+                    ? `Max failures reached (${consecutiveFailures}/${maxFailures})${lastErrorMessage ? `: ${lastErrorMessage}` : ""}`
+                    : exitReason === "error"
+                        ? `Unrecoverable error${lastErrorMessage ? `: ${lastErrorMessage}` : ""}`
+                        : exitReason === "end_loop_signal"
+                            ? "Agent requested end of loop"
+                            : exitReason === "max_iterations"
+                                ? `Completed all ${maxLoops} iterations`
+                                : exitReason === "no_tasks"
+                                    ? "No eligible tasks remaining"
+                                    : exitReason === "explicit_tasks_done"
+                                        ? "All explicit tasks completed"
+                                        : `Loop ended: ${exitReason}`;
                 await appendEvent(specDir, {
                     session_id: sessionId,
                     type: "session.end",
@@ -1391,9 +1205,10 @@ export function registerRalphCommand(program) {
                         status,
                         consecutiveFailures,
                         exitReason,
+                        closeReason,
                     },
                 });
-                await updateSessionStatus(specDir, sessionId, status);
+                await closeSession(specDir, sessionId, status, closeReason);
             }
             console.log(chalk.green(`\n${"─".repeat(60)}`));
             success("Ralph loop completed");