@aiwg/cli 0.0.0-bootstrap.0 → 2026.7.17

package/dist/src/cli/handlers/ralph-launcher.js

@@ -0,0 +1,717 @@
+/**
+ * Ralph External Process Launcher
+ *
+ * Spawns the external Ralph supervisor as a detached background process
+ * that survives terminal closure and can be managed across sessions.
+ *
+ * @implements @.aiwg/working/issue-ralph-external-completion.md
+ * @issue #275
+ * @security docs/ralph-external-security.md
+ *
+ * SECURITY WARNING
+ * ================
+ * This module launches Claude Code sessions with --dangerously-skip-permissions.
+ * Spawned sessions can read/write ANY file and execute ANY command without
+ * user confirmation. Sessions run as detached daemons for extended periods
+ * without human oversight.
+ *
+ * BEFORE USING:
+ * - Read docs/ralph-external-security.md
+ * - Understand all security implications
+ * - Set appropriate limits (budget, iterations, timeout)
+ * - Ensure clean git state for rollback capability
+ * - Have monitoring and abort procedures ready
+ */
+import { spawn } from 'child_process';
+import { join } from 'path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync, rmSync, readdirSync, copyFileSync, statSync, openSync, readSync, closeSync, } from 'fs';
+import { getProviderConfig } from '../agent-spawn.js';
+import { AiwgError, EXIT_CODES } from '../errors.js';
+import { projectAiwgPath } from '../../config/project-artifacts.js';
+/**
+ * Get the path to the external Ralph orchestrator
+ */
+export function getOrchestratorPath(frameworkRoot) {
+    return join(frameworkRoot, 'tools', 'ralph-external', 'index.mjs');
+}
+/**
+ * Get the registry directory path
+ */
+export function getRegistryDir(projectRoot) {
+    return projectAiwgPath(projectRoot, 'ralph-external');
+}
+/**
+ * Get the registry file path
+ */
+export function getRegistryPath(projectRoot) {
+    return join(getRegistryDir(projectRoot), 'registry.json');
+}
+/**
+ * Generate a unique loop ID
+ */
+export function generateLoopId(objective) {
+    const slug = objective
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 30);
+    const shortId = Date.now().toString(36) + Math.random().toString(36).slice(2, 6);
+    return `ralph-${slug}-${shortId}`;
+}
+/**
+ * Build command-line arguments for the external Ralph process
+ */
+export function buildArgs(options) {
+    const args = [options.objective];
+    args.push('--completion', options.completionCriteria);
+    if (options.maxIterations) {
+        args.push('--max-iterations', String(options.maxIterations));
+    }
+    if (options.model) {
+        args.push('--model', options.model);
+    }
+    if (options.budget) {
+        args.push('--budget', String(options.budget));
+    }
+    if (options.maxTotalTokens) {
+        args.push('--max-total-tokens', String(options.maxTotalTokens));
+    }
+    if (options.maxOutputTokens) {
+        args.push('--max-output-tokens', String(options.maxOutputTokens));
+    }
+    if (options.maxToolCalls) {
+        args.push('--max-tool-calls', String(options.maxToolCalls));
+    }
+    if (options.maxTotalCost) {
+        args.push('--max-total-cost', String(options.maxTotalCost));
+    }
+    if (options.maxWallClockMinutes) {
+        args.push('--max-wall-clock-minutes', String(options.maxWallClockMinutes));
+    }
+    if (options.explorationQuota) {
+        args.push('--exploration-quota', String(options.explorationQuota));
+    }
+    if (options.budgetStopPolicy) {
+        args.push('--budget-stop-policy', options.budgetStopPolicy);
+    }
+    if (options.timeout) {
+        args.push('--timeout', String(options.timeout));
+    }
+    if (options.mcpConfig) {
+        args.push('--mcp-config', options.mcpConfig);
+    }
+    if (options.giteaIssue) {
+        args.push('--gitea-issue');
+    }
+    if (options.memory !== undefined) {
+        args.push('--memory', String(options.memory));
+    }
+    if (options.crossTask === false) {
+        args.push('--no-cross-task');
+    }
+    if (options.enableAnalytics === false) {
+        args.push('--no-analytics');
+    }
+    if (options.enableBestOutput === false) {
+        args.push('--no-best-output');
+    }
+    if (options.enableEarlyStopping === false) {
+        args.push('--no-early-stopping');
+    }
+    if (options.provider && options.provider !== 'claude') {
+        args.push('--provider', options.provider);
+    }
+    if (options.dangerous) {
+        args.push('--dangerous');
+    }
+    if (options.params) {
+        args.push('--params', options.params);
+    }
+    if (options.verbose) {
+        args.push('--verbose');
+    }
+    if (options.logFile) {
+        args.push('--log-file', options.logFile);
+    }
+    return args;
+}
+/**
+ * Enforce `parallelism.max_parallel_ralph_loops` from `.aiwg/aiwg.config`.
+ * Hard-fails (throws AiwgError) when the count of running + live Ralph loops
+ * already meets or exceeds the cap. Non-fatal when no config or config read
+ * fails — caller proceeds with launch.
+ *
+ * Extracted so the cap-check logic is unit-testable independently of the
+ * detached-process spawn machinery.
+ *
+ * @implements #1361
+ */
+export async function assertRalphParallelismCap(projectRoot) {
+    let cfg;
+    let resolveParallelism;
+    try {
+        const mod = await import('../../config/aiwg-config.js');
+        resolveParallelism = mod.resolveParallelism;
+        cfg = await mod.readAiwgConfig(projectRoot);
+    }
+    catch {
+        return; // Config unreadable — non-fatal, let launch proceed
+    }
+    if (!cfg)
+        return;
+    const resolved = resolveParallelism(cfg.parallelism, cfg.providers[0]);
+    const launcherRegistry = loadLauncherRegistry(projectRoot);
+    const activeCount = Object.values(launcherRegistry.loops).filter((l) => l.status === 'running' && isProcessAlive(l.pid)).length;
+    if (activeCount >= resolved.max_parallel_ralph_loops) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_PARALLELISM_CAP',
+            message: `Project parallelism cap reached: ${activeCount}/${resolved.max_parallel_ralph_loops} Ralph loops already running.`,
+            hint: `Wait for an existing loop to finish ('aiwg ralph-status'), or bump the cap ('aiwg config set --project parallelism.max_parallel_ralph_loops N').`,
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+}
+/**
+ * Launch the external Ralph process as a detached daemon
+ */
+export async function launchExternalRalph(frameworkRoot, projectRoot, options) {
+    const orchestratorPath = getOrchestratorPath(frameworkRoot);
+    if (!existsSync(orchestratorPath)) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_ORCHESTRATOR_MISSING',
+            message: `External Ralph orchestrator not found at: ${orchestratorPath}`,
+            hint: 'Run `aiwg use ralph` to deploy the orchestrator, or `npm run build` in the dev repo',
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+    const registryDir = getRegistryDir(projectRoot);
+    mkdirSync(registryDir, { recursive: true });
+    // #1361: Enforce project-level max_parallel_ralph_loops cap. Hard fail
+    // (not queue) — Ralph loops are long-running, silent queueing would be
+    // surprising. Tell the operator what's running and how to lift the cap.
+    await assertRalphParallelismCap(projectRoot);
+    const loopId = options.loopId || generateLoopId(options.objective);
+    const loopDir = join(registryDir, 'loops', loopId);
+    mkdirSync(loopDir, { recursive: true });
+    // Create output file for the detached process
+    const outputFile = join(loopDir, 'daemon-output.log');
+    const sessionStdoutFile = join(loopDir, 'outputs', '001-stdout.log');
+    const sessionStderrFile = join(loopDir, 'outputs', '001-stderr.log');
+    const promptFile = join(loopDir, 'prompts', '001-prompt.md');
+    // Build arguments
+    const args = buildArgs(options);
+    // Create output file descriptors
+    const { openSync, closeSync } = await import('fs');
+    const outFd = openSync(outputFile, 'w');
+    // Spawn detached process
+    const child = spawn('node', [orchestratorPath, ...args], {
+        detached: true,
+        stdio: ['ignore', outFd, outFd],
+        cwd: projectRoot,
+        env: {
+            ...process.env,
+            RALPH_LOOP_ID: loopId,
+            RALPH_DETACHED: 'true',
+            ...(options.provider ? { RALPH_PROVIDER: options.provider } : {}),
+            ...(options.dangerous ? {
+                RALPH_DANGEROUS: 'true',
+                RALPH_DANGEROUS_FLAG: getProviderConfig(options.provider ?? 'claude').dangerousFlag ?? '',
+            } : {}),
+            ...(options.params ? { RALPH_EXTRA_PARAMS: options.params } : {}),
+        },
+    });
+    // Detach from parent - let it run independently
+    child.unref();
+    closeSync(outFd);
+    const pid = child.pid;
+    if (!pid) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_SPAWN_FAILED',
+            message: 'Failed to start external Ralph process — no PID returned by spawn',
+            hint: 'Check system resources (ulimit -u) and that `node` is on PATH',
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+    // Record the loop in our launcher registry (backup to the external-multi-loop-state-manager)
+    const launcherRegistry = loadLauncherRegistry(projectRoot);
+    launcherRegistry.loops[loopId] = {
+        loopId,
+        pid,
+        objective: options.objective,
+        completionCriteria: options.completionCriteria,
+        status: 'running',
+        startedAt: new Date().toISOString(),
+        lastUpdate: new Date().toISOString(),
+        iteration: 0,
+        maxIterations: options.maxIterations || 5,
+        outputFile,
+        sessionStdoutFile,
+        sessionStderrFile,
+        promptFile,
+        provider: options.provider,
+    };
+    saveLauncherRegistry(projectRoot, launcherRegistry);
+    return {
+        success: true,
+        loopId,
+        pid,
+        message: `agent loop started (${loopId}). Check status: aiwg ralph-status`,
+        registryPath: getRegistryPath(projectRoot),
+    };
+}
+/**
+ * Load the launcher registry
+ */
+export function loadLauncherRegistry(projectRoot) {
+    const registryPath = join(getRegistryDir(projectRoot), 'launcher-registry.json');
+    if (!existsSync(registryPath)) {
+        return {
+            version: '1.0.0',
+            loops: {},
+            updatedAt: new Date().toISOString(),
+        };
+    }
+    try {
+        return JSON.parse(readFileSync(registryPath, 'utf8'));
+    }
+    catch {
+        return {
+            version: '1.0.0',
+            loops: {},
+            updatedAt: new Date().toISOString(),
+        };
+    }
+}
+/**
+ * Save the launcher registry
+ */
+export function saveLauncherRegistry(projectRoot, registry) {
+    const registryDir = getRegistryDir(projectRoot);
+    mkdirSync(registryDir, { recursive: true });
+    const registryPath = join(registryDir, 'launcher-registry.json');
+    registry.updatedAt = new Date().toISOString();
+    writeFileSync(registryPath, JSON.stringify(registry, null, 2));
+}
+/**
+ * Check if a process is still running
+ */
+export function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Get status of all agent loops.
+ * Detects stale entries (>24h without heartbeat) and auto-cleans completed entries.
+ */
+export function getLoopStatuses(projectRoot, options = {}) {
+    const registry = loadLauncherRegistry(projectRoot);
+    const statuses = [];
+    const staleThresholdMs = 24 * 60 * 60 * 1000; // 24 hours
+    let registryDirty = false;
+    for (const [loopId, entry] of Object.entries(registry.loops)) {
+        // Update status based on process liveness
+        if (entry.status === 'running' && !isProcessAlive(entry.pid)) {
+            // Process died - mark as failed unless we can determine it completed
+            const stateFile = join(getRegistryDir(projectRoot), 'loops', loopId, 'session-state.json');
+            if (existsSync(stateFile)) {
+                try {
+                    const state = JSON.parse(readFileSync(stateFile, 'utf8'));
+                    entry.status = state.status || 'failed';
+                    entry.iteration = state.currentIteration || entry.iteration;
+                }
+                catch {
+                    entry.status = 'failed';
+                }
+            }
+            else {
+                entry.status = 'failed';
+            }
+            registryDirty = true;
+        }
+        // Detect stale entries (>24h since last update)
+        const lastUpdateAge = Date.now() - new Date(entry.lastUpdate).getTime();
+        if (lastUpdateAge > staleThresholdMs && entry.status === 'running') {
+            entry.stale = true;
+        }
+        // Auto-clean completed entries if requested
+        if (options.autoCleanCompleted && (entry.status === 'completed')) {
+            cleanupCompletedLoop(projectRoot, loopId);
+            registryDirty = true;
+            continue; // Don't include in statuses
+        }
+        statuses.push(entry);
+    }
+    if (registryDirty) {
+        saveLauncherRegistry(projectRoot, registry);
+    }
+    return statuses;
+}
+/**
+ * Abort a running agent loop by killing its process
+ */
+export function abortLoop(projectRoot, loopId) {
+    const registry = loadLauncherRegistry(projectRoot);
+    // If no loopId specified, find the most recent running loop
+    if (!loopId) {
+        const runningLoops = Object.values(registry.loops)
+            .filter((l) => l.status === 'running' && isProcessAlive(l.pid))
+            .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+        if (runningLoops.length === 0) {
+            return { success: false, message: 'No running agent loops found' };
+        }
+        loopId = runningLoops[0].loopId;
+    }
+    const entry = registry.loops[loopId];
+    if (!entry) {
+        return { success: false, message: `Loop not found: ${loopId}` };
+    }
+    if (!isProcessAlive(entry.pid)) {
+        entry.status = 'aborted';
+        saveLauncherRegistry(projectRoot, registry);
+        return { success: true, message: `Loop ${loopId} was already stopped` };
+    }
+    try {
+        process.kill(entry.pid, 'SIGTERM');
+        entry.status = 'aborted';
+        entry.lastUpdate = new Date().toISOString();
+        saveLauncherRegistry(projectRoot, registry);
+        return { success: true, message: `Aborted loop ${loopId} (PID: ${entry.pid})` };
+    }
+    catch (error) {
+        return {
+            success: false,
+            message: `Failed to kill process ${entry.pid}: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
+/**
+ * Resume an interrupted agent loop
+ */
+export async function resumeLoop(frameworkRoot, projectRoot, loopId, overrides) {
+    const orchestratorPath = getOrchestratorPath(frameworkRoot);
+    if (!existsSync(orchestratorPath)) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_ORCHESTRATOR_MISSING',
+            message: `External Ralph orchestrator not found at: ${orchestratorPath}`,
+            hint: 'Run `aiwg use ralph` to deploy the orchestrator',
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+    // Build resume arguments
+    const args = ['--resume'];
+    if (overrides?.maxIterations) {
+        args.push('--max-iterations', String(overrides.maxIterations));
+    }
+    const registryDir = getRegistryDir(projectRoot);
+    mkdirSync(registryDir, { recursive: true });
+    // Find loop to resume
+    const registry = loadLauncherRegistry(projectRoot);
+    let targetLoopId = loopId;
+    if (!targetLoopId) {
+        // Find most recent non-running loop
+        const resumable = Object.values(registry.loops)
+            .filter((l) => l.status !== 'running' || !isProcessAlive(l.pid))
+            .sort((a, b) => new Date(b.lastUpdate).getTime() - new Date(a.lastUpdate).getTime());
+        if (resumable.length === 0) {
+            throw new AiwgError({
+                code: 'ERR_RALPH_NO_RESUMABLE',
+                message: 'No loops available to resume',
+                hint: 'Start a new loop with: aiwg ralph "<objective>"',
+                exitCode: EXIT_CODES.USAGE,
+            });
+        }
+        targetLoopId = resumable[0].loopId;
+    }
+    const entry = registry.loops[targetLoopId];
+    if (!entry) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_LOOP_NOT_FOUND',
+            message: `Loop not found: ${targetLoopId}`,
+            hint: 'List available loops with: aiwg ralph-status',
+            exitCode: EXIT_CODES.USAGE,
+        });
+    }
+    const loopDir = join(registryDir, 'loops', targetLoopId);
+    const outputFile = join(loopDir, 'daemon-output.log');
+    // Create output file descriptor
+    const { openSync, closeSync } = await import('fs');
+    const outFd = openSync(outputFile, 'a'); // Append mode for resume
+    // Spawn detached process
+    const child = spawn('node', [orchestratorPath, ...args], {
+        detached: true,
+        stdio: ['ignore', outFd, outFd],
+        cwd: projectRoot,
+        env: {
+            ...process.env,
+            RALPH_LOOP_ID: targetLoopId,
+            RALPH_DETACHED: 'true',
+        },
+    });
+    child.unref();
+    closeSync(outFd);
+    const pid = child.pid;
+    if (!pid) {
+        throw new AiwgError({
+            code: 'ERR_RALPH_SPAWN_FAILED',
+            message: 'Failed to start external Ralph process — no PID returned by spawn',
+            hint: 'Check system resources (ulimit -u) and that `node` is on PATH',
+            exitCode: EXIT_CODES.GENERAL,
+        });
+    }
+    // Update registry
+    entry.pid = pid;
+    entry.status = 'running';
+    entry.lastUpdate = new Date().toISOString();
+    if (overrides?.maxIterations) {
+        entry.maxIterations = overrides.maxIterations;
+    }
+    saveLauncherRegistry(projectRoot, registry);
+    return {
+        success: true,
+        loopId: targetLoopId,
+        pid,
+        message: `Resumed agent loop (${targetLoopId}). Check status: aiwg ralph-status`,
+        registryPath: getRegistryPath(projectRoot),
+    };
+}
+/**
+ * Clean up a completed loop: remove from launcher-registry and delete working state.
+ * Preserves completion reports by moving them to the ralph-external root before deletion.
+ *
+ * @param projectRoot - Project root directory
+ * @param loopId - Loop ID to clean up
+ * @param options - Cleanup options
+ * @returns Object with success status and details
+ */
+export function cleanupCompletedLoop(projectRoot, loopId, options = {}) {
+    const registryDir = getRegistryDir(projectRoot);
+    const loopDir = join(registryDir, 'loops', loopId);
+    const preserved = [];
+    // Preserve completion reports before deleting the loop directory
+    if (existsSync(loopDir)) {
+        try {
+            const files = readdirSync(loopDir);
+            for (const file of files) {
+                if (file.startsWith('completion-') && file.endsWith('.md')) {
+                    const dest = join(registryDir, file);
+                    copyFileSync(join(loopDir, file), dest);
+                    preserved.push(dest);
+                }
+            }
+        }
+        catch {
+            // Non-fatal: proceed with cleanup even if report preservation fails
+        }
+        if (options.archive) {
+            // Move to archive instead of deleting
+            const archiveDir = join(registryDir, 'archive', loopId);
+            mkdirSync(join(registryDir, 'archive'), { recursive: true });
+            try {
+                const { renameSync } = require('fs');
+                renameSync(loopDir, archiveDir);
+            }
+            catch {
+                // If rename fails (cross-device), fall through to deletion
+            }
+        }
+        else {
+            // Delete working state
+            try {
+                rmSync(loopDir, { recursive: true, force: true });
+            }
+            catch {
+                // Non-fatal
+            }
+        }
+    }
+    // Remove entry from launcher registry
+    const registry = loadLauncherRegistry(projectRoot);
+    if (registry.loops[loopId]) {
+        delete registry.loops[loopId];
+        saveLauncherRegistry(projectRoot, registry);
+    }
+    return {
+        success: true,
+        message: `Cleaned up loop ${loopId}`,
+        preserved,
+    };
+}
+/**
+ * Clean up internal Ralph state after successful completion.
+ * Deletes current-loop.json, heartbeats, and iteration working state.
+ * Preserves completion report files.
+ *
+ * @param projectRoot - Project root directory
+ * @returns Object with success status and what was cleaned
+ */
+export function cleanupInternalRalph(projectRoot) {
+    const ralphDir = projectAiwgPath(projectRoot, 'ralph');
+    const cleaned = [];
+    const preserved = [];
+    if (!existsSync(ralphDir)) {
+        return { success: true, cleaned: [], preserved: [] };
+    }
+    // Check if current-loop.json exists and is completed
+    const currentLoopPath = join(ralphDir, 'current-loop.json');
+    if (existsSync(currentLoopPath)) {
+        try {
+            const state = JSON.parse(readFileSync(currentLoopPath, 'utf8'));
+            if (state.status === 'completed' || state.status === 'success') {
+                rmSync(currentLoopPath, { force: true });
+                cleaned.push('current-loop.json');
+            }
+        }
+        catch {
+            // If we can't parse it, leave it alone
+        }
+    }
+    // Clean up heartbeats directory
+    const heartbeatsDir = join(ralphDir, 'heartbeats');
+    if (existsSync(heartbeatsDir)) {
+        try {
+            rmSync(heartbeatsDir, { recursive: true, force: true });
+            cleaned.push('heartbeats/');
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    // Clean up iterations working state (but preserve completion reports)
+    const iterationsDir = join(ralphDir, 'iterations');
+    if (existsSync(iterationsDir)) {
+        try {
+            rmSync(iterationsDir, { recursive: true, force: true });
+            cleaned.push('iterations/');
+        }
+        catch {
+            // Non-fatal
+        }
+    }
+    // Log preserved completion reports
+    try {
+        const files = readdirSync(ralphDir);
+        for (const file of files) {
+            if (file.startsWith('completion-') && file.endsWith('.md')) {
+                preserved.push(file);
+            }
+        }
+    }
+    catch {
+        // Non-fatal
+    }
+    return { success: true, cleaned, preserved };
+}
+/**
+ * Clean up completed/failed loops from registry
+ */
+export function cleanupRegistry(projectRoot, keepDays = 7) {
+    const registry = loadLauncherRegistry(projectRoot);
+    const cutoff = Date.now() - keepDays * 24 * 60 * 60 * 1000;
+    let cleaned = 0;
+    for (const [loopId, entry] of Object.entries(registry.loops)) {
+        if (entry.status !== 'running') {
+            const lastUpdate = new Date(entry.lastUpdate).getTime();
+            if (lastUpdate < cutoff) {
+                delete registry.loops[loopId];
+                cleaned++;
+            }
+        }
+    }
+    if (cleaned > 0) {
+        saveLauncherRegistry(projectRoot, registry);
+    }
+    return cleaned;
+}
+/**
+ * Attach to a running agent loop's output stream.
+ *
+ * Tails the loop's daemon-output.log to stdout in real-time.
+ * Ctrl+C detaches (the background loop keeps running).
+ * Returns a Promise that resolves when the user detaches or the loop exits.
+ */
+export function attachToLoopOutput(projectRoot, loopId) {
+    const registry = loadLauncherRegistry(projectRoot);
+    const entries = Object.values(registry.loops);
+    let entry;
+    if (loopId) {
+        entry = registry.loops[loopId];
+        if (!entry) {
+            return Promise.reject(new Error(`Loop not found: ${loopId}`));
+        }
+    }
+    else {
+        // Use most recently started running loop
+        const running = entries
+            .filter((e) => e.status === 'running' && isProcessAlive(e.pid))
+            .sort((a, b) => new Date(b.startedAt).getTime() - new Date(a.startedAt).getTime());
+        if (running.length === 0) {
+            return Promise.reject(new Error('No running loops to attach to. Use --loop-id to specify a loop.'));
+        }
+        entry = running[0];
+    }
+    const outputFile = entry.outputFile;
+    const attachedLoopId = entry.loopId;
+    return new Promise((resolve) => {
+        let offset = 0;
+        // Print any existing content
+        try {
+            const stats = statSync(outputFile);
+            if (stats.size > 0) {
+                const fd = openSync(outputFile, 'r');
+                const buf = Buffer.alloc(stats.size);
+                readSync(fd, buf, 0, stats.size, 0);
+                closeSync(fd);
+                process.stdout.write(buf);
+                offset = stats.size;
+            }
+        }
+        catch {
+            // Log file may not exist yet — will appear shortly
+        }
+        // Poll for new content every 250 ms. .unref() so the interval cannot
+        // outlive the resolve() path and hold the event loop alive.
+        const interval = setInterval(() => {
+            try {
+                const stats = statSync(outputFile);
+                if (stats.size > offset) {
+                    const newBytes = stats.size - offset;
+                    const fd = openSync(outputFile, 'r');
+                    const buf = Buffer.alloc(newBytes);
+                    readSync(fd, buf, 0, newBytes, offset);
+                    closeSync(fd);
+                    process.stdout.write(buf);
+                    offset = stats.size;
+                }
+                // Stop polling if the process has exited
+                if (!isProcessAlive(registry.loops[attachedLoopId]?.pid ?? 0)) {
+                    clearInterval(interval);
+                    process.removeListener('SIGINT', onSigint);
+                    process.stdout.write('\n[ralph-attach] Loop process has exited.\n');
+                    resolve();
+                }
+            }
+            catch {
+                // File may be temporarily unavailable during rotation — ignore
+            }
+        }, 250);
+        interval.unref?.();
+        // Ctrl+C detaches without stopping the loop. Registered with named handler
+        // + process.once so we can remove it cleanly on process-exit path and so
+        // it does not accumulate across re-attach cycles within a single CLI run.
+        const onSigint = () => {
+            clearInterval(interval);
+            process.stdout.write('\n\nDetached from loop output. Loop continues in background.\n');
+            process.stdout.write(`  Status:     aiwg ralph-status\n`);
+            process.stdout.write(`  Re-attach:  aiwg ralph-attach --loop-id ${attachedLoopId}\n`);
+            process.stdout.write(`  Abort:      aiwg ralph-abort --loop-id ${attachedLoopId}\n`);
+            resolve();
+        };
+        process.once('SIGINT', onSigint);
+    });
+}
+//# sourceMappingURL=ralph-launcher.js.map