vigthoria-cli 1.13.18 → 1.13.22

package/dist/commands/doctor-registration.js

@@ -0,0 +1,200 @@
+import { createRequire } from 'node:module';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import axios from 'axios';
+import chalk from 'chalk';
+import { isIOSEnvironment, resolveClientOsSlug } from '../utils/clientManifest.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
+import { sanitizeUserFacingErrorText } from '../utils/api.js';
+import { getCliStateFile, isOfflineMode, isUpdateCheckSuppressed } from '../utils/cli-state.js';
+import { CliCommandError, formatSuccessJson } from '../utils/command-contract.js';
+export function registerDoctorCommand(program, config, logger, version) {
+    program
+        .command('doctor')
+        .description('Run local Vigthoria CLI diagnostics (no network calls unless --check-api)')
+        .option('--check-api', 'Also probe Vigthoria API reachability', false)
+        .option('--json', 'Emit machine-readable JSON output', false)
+        .action(async (options) => {
+        const apiUrl = String(config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
+        const modelsApiUrl = String(config.get('modelsApiUrl') || 'https://api.vigthoria.io').replace(/\/$/, '');
+        const offline = isOfflineMode();
+        const updateSuppressed = isUpdateCheckSuppressed();
+        const subscription = config.get('subscription') || { plan: null, status: null, expiresAt: null };
+        const iosSandbox = isIOSEnvironment();
+        const platformSupport = iosSandbox
+            ? 'experimental-mobile-terminal-sandbox'
+            : process.platform === 'darwin'
+                ? 'supported-macos-desktop'
+                : process.platform === 'win32' || process.platform === 'linux'
+                    ? 'supported-desktop'
+                    : 'unsupported';
+        const nodeMatch = process.versions.node.match(/^(\d+)\.(\d+)/);
+        const nodeCompatible = Boolean(nodeMatch && (Number(nodeMatch[1]) > 20
+            || (Number(nodeMatch[1]) === 20 && Number(nodeMatch[2]) >= 19)));
+        const runtimeRequire = createRequire(import.meta.url);
+        const requiredRuntimePackages = ['axios', 'commander', 'inquirer', 'ws'];
+        const missingRuntimePackages = requiredRuntimePackages.filter((name) => {
+            try {
+                runtimeRequire.resolve(name);
+                return false;
+            }
+            catch {
+                return true;
+            }
+        });
+        const sessionsDir = path.join(os.homedir(), '.vigthoria', 'sessions');
+        let sessionStorageWritable = false;
+        let latestCheckpoint = null;
+        try {
+            fs.mkdirSync(sessionsDir, { recursive: true, mode: 0o700 });
+            const probePath = path.join(sessionsDir, `.doctor-${process.pid}-${Date.now()}.tmp`);
+            fs.writeFileSync(probePath, '{}', { encoding: 'utf8', mode: 0o600 });
+            fs.unlinkSync(probePath);
+            sessionStorageWritable = true;
+            const latestSessionFile = fs.readdirSync(sessionsDir)
+                .filter((name) => name.endsWith('.json') && name !== 'index.json')
+                .map((name) => ({ name, mtime: fs.statSync(path.join(sessionsDir, name)).mtimeMs }))
+                .sort((left, right) => right.mtime - left.mtime)[0]?.name;
+            if (latestSessionFile) {
+                const document = JSON.parse(fs.readFileSync(path.join(sessionsDir, latestSessionFile), 'utf8'));
+                const persisted = document?.data && typeof document.data === 'object' ? document.data : document;
+                const checkpoint = persisted?.activeAgentRun;
+                if (checkpoint && typeof checkpoint === 'object') {
+                    latestCheckpoint = {
+                        executionId: checkpoint.executionId || null,
+                        status: checkpoint.status || null,
+                        updatedAt: checkpoint.updatedAt || null,
+                        resumable: ['submitted', 'running', 'failed'].includes(String(checkpoint.status || '')),
+                    };
+                }
+            }
+        }
+        catch {
+            sessionStorageWritable = false;
+        }
+        const envToken = String(process.env.VIGTHORIA_AUTH_TOKEN || process.env.VIGTHORIA_TOKEN || '').trim();
+        const configuredToken = envToken || String(config.get('authToken') || '').trim();
+        const tokenSegments = configuredToken ? configuredToken.split('.').length : 0;
+        const report = {
+            cliVersion: version,
+            nodeVersion: process.version,
+            nodeCompatible,
+            runtimeDependencies: missingRuntimePackages.length === 0 ? 'complete' : `missing: ${missingRuntimePackages.join(', ')}`,
+            platform: `${process.platform} ${process.arch}`,
+            clientOs: resolveClientOsSlug(),
+            platformSupport,
+            platformLimitations: iosSandbox
+                ? 'Not a native iOS app. Requires an iSH-like Linux terminal with Node.js >=20.19, npm and filesystem access; Workbench and device tooling are unavailable.'
+                : null,
+            cwd: process.cwd(),
+            homeDir: os.homedir(),
+            configPath: config.getConfigPath(),
+            stateFile: getCliStateFile(),
+            apiUrl,
+            modelsApiUrl,
+            loggedIn: config.isAuthenticated(),
+            authToken: configuredToken
+                ? { present: true, source: envToken ? 'environment' : 'secure-config', structure: tokenSegments === 3 ? 'jwt' : 'opaque' }
+                : { present: false, source: null, structure: null },
+            sessionPersistence: {
+                directory: sessionsDir,
+                writable: sessionStorageWritable,
+                latestCheckpoint,
+            },
+            subscriptionPlan: subscription.plan || null,
+            subscriptionStatus: subscription.status || null,
+            offlineMode: offline,
+            updateCheckSuppressed: updateSuppressed,
+            envOverrides: {
+                VIGTHORIA_API_URL: process.env.VIGTHORIA_API_URL || null,
+                VIGTHORIA_V3_AGENT_URL: process.env.VIGTHORIA_V3_AGENT_URL || null,
+                VIGTHORIA_OFFLINE: process.env.VIGTHORIA_OFFLINE || null,
+                VIGTHORIA_TOKEN: process.env.VIGTHORIA_TOKEN ? '<set>' : null,
+                HYPERLOOP_SERVICE_KEY: process.env.HYPERLOOP_SERVICE_KEY ? '<set>' : null,
+                V3_SERVICE_KEY: process.env.V3_SERVICE_KEY ? '<set>' : null,
+            },
+        };
+        if (options.checkApi && !offline) {
+            const api = createAPIClient(config, logger);
+            if (configuredToken) {
+                try {
+                    const tokenCheck = await api.validateToken({ allowNetworkFailOpen: false, enforceTokenShape: true });
+                    report.authValidation = tokenCheck.valid ? 'authenticated' : `failed (${tokenCheck.error || 'invalid token'})`;
+                }
+                catch (error) {
+                    report.authValidation = `unreachable (${sanitizeUserFacingErrorText(error.message)})`;
+                }
+            }
+            else {
+                report.authValidation = 'not checked (login required)';
+            }
+            try {
+                const probe = await axios.get(`${apiUrl}/api/health`, { timeout: 12000, validateStatus: () => true });
+                report.apiHealth = probe.status >= 200 && probe.status < 400 ? 'online' : `status ${probe.status}`;
+            }
+            catch (error) {
+                report.apiHealth = `unreachable (${error.message})`;
+            }
+            try {
+                const probe = await axios.get(`${modelsApiUrl}/health`, { timeout: 12000, validateStatus: () => true });
+                const body = typeof probe.data === 'string' ? probe.data : JSON.stringify(probe.data || {});
+                report.modelsApiHealth = probe.status >= 200 && probe.status < 400
+                    ? 'online'
+                    : probe.status === 503 && /pre-release validation|closed/i.test(body)
+                        ? 'pre-release-closed (Agent mode uses the Coder gateway)'
+                        : `status ${probe.status}`;
+            }
+            catch (error) {
+                report.modelsApiHealth = `unreachable (${error.message})`;
+            }
+            if (configuredToken) {
+                try {
+                    const capabilities = await api.getCapabilityTruthStatus({ workspacePath: process.cwd() });
+                    report.agentInfrastructure = {
+                        overall: capabilities.overallOk ? 'online' : 'degraded',
+                        v3Agent: capabilities.v3Agent.ok ? 'online' : capabilities.v3Agent.error || 'offline',
+                        hyperLoop: capabilities.hyperLoop.ok ? 'online' : capabilities.hyperLoop.error || 'offline',
+                        repoMemory: capabilities.repoMemory.ok ? 'online' : capabilities.repoMemory.error || 'offline',
+                    };
+                }
+                catch (error) {
+                    report.agentInfrastructure = `unreachable (${sanitizeUserFacingErrorText(error.message)})`;
+                }
+            }
+        }
+        const printHumanReport = () => {
+            console.log(chalk.bold('Vigthoria CLI diagnostics'));
+            for (const [key, value] of Object.entries(report)) {
+                if (value && typeof value === 'object') {
+                    console.log(chalk.gray(`- ${key}:`));
+                    for (const [subKey, subVal] of Object.entries(value)) {
+                        console.log(chalk.gray(`    - ${subKey}: ${subVal ?? '(none)'}`));
+                    }
+                }
+                else {
+                    console.log(chalk.gray(`- ${key}: ${value ?? '(none)'}`));
+                }
+            }
+            if (!options.checkApi) {
+                console.log(chalk.gray('\nTip: pass --check-api to verify API reachability.'));
+            }
+        };
+        const requiredLocalChecksPassed = nodeCompatible && missingRuntimePackages.length === 0 && sessionStorageWritable;
+        const coderReachable = !options.checkApi || offline || report.apiHealth === 'online';
+        if (!requiredLocalChecksPassed || !coderReachable) {
+            if (!options.json)
+                printHumanReport();
+            throw new CliCommandError('One or more required doctor checks failed.', {
+                code: 'DOCTOR_CHECK_FAILED',
+                details: report,
+            });
+        }
+        if (options.json) {
+            console.log(formatSuccessJson('doctor', report));
+        }
+        else {
+            printHumanReport();
+        }
+    });
+}

package/dist/commands/edit.js

@@ -4,8 +4,9 @@
 import chalk from 'chalk';
 import inquirer from 'inquirer';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError } from '../utils/api.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
 import { FileUtils } from '../utils/files.js';
+import { CliCommandError, commandFailure } from '../utils/command-contract.js';
 export class EditCommand {
     config;
     logger;
@@ -14,26 +15,23 @@ export class EditCommand {
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
-        this.api = new APIClient(config, logger);
+        this.api = createAPIClient(config, logger);
         this.fileUtils = new FileUtils(process.cwd(), config.get('project').ignorePatterns);
     }
     async run(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         this.logger.section(`Editing: ${file.relativePath}`);
         console.log(chalk.gray(`Language: ${file.language} | Lines: ${file.lines}`));
@@ -43,13 +41,11 @@ export class EditCommand {
         if (!instruction) {
             // --apply requires --instruction to avoid hanging on non-interactive terminals
             if (options.apply) {
-                this.logger.error('The --apply flag requires --instruction. Example: vigthoria edit file.ts --apply --instruction "fix the bug"');
-                return;
+                throw new CliCommandError('The --apply flag requires --instruction. Example: vigthoria edit file.ts --apply --instruction "fix the bug"', { code: 'INVALID_OPTION_COMBINATION', category: 'usage' });
             }
             // Non-TTY stdin cannot prompt interactively
             if (!process.stdin.isTTY) {
-                this.logger.error('No --instruction provided and stdin is not interactive. Use: vigthoria edit file.ts --instruction "..."');
-                return;
+                throw new CliCommandError('No --instruction provided and stdin is not interactive. Use: vigthoria edit file.ts --instruction "..."', { code: 'INSTRUCTION_REQUIRED', category: 'usage' });
             }
             const answer = await inquirer.prompt([
                 {
@@ -100,15 +96,14 @@ Return the complete modified file content:`,
             // Extract code from response
             let modifiedCode = this.extractCode(response.message, file.language);
             if (!modifiedCode) {
-                this.logger.error('Failed to generate valid code changes');
-                return;
+                throw new CliCommandError('Failed to generate valid code changes', { code: 'EDIT_RESPONSE_INVALID' });
             }
             // Always deduplicate — extractCode only dedupes on the no-fence
             // fallback path, so fenced responses (the common case) need this.
             modifiedCode = this.deduplicateCode(modifiedCode);
             // Show diff and apply
             if (options.apply) {
-                await this.applyFix(file.path, file.content, modifiedCode);
+                await this.applyFix(file.path, modifiedCode);
             }
             else {
                 await this.showDiffAndConfirm(file.path, file.content, modifiedCode);
@@ -116,27 +111,23 @@ Return the complete modified file content:`,
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'EDIT_FAILED' });
         }
     }
     async fix(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         this.logger.section(`Fixing: ${file.relativePath}`);
         console.log(chalk.gray(`Fix type: ${options.type} | Language: ${file.language}`));
@@ -159,7 +150,7 @@ Return the complete modified file content:`,
                     console.log(chalk.yellow('1. Operator/character-level fix detected'));
                     console.log();
                     if (options.apply) {
-                        await this.applyFix(file.path, file.content, result.fixed);
+                        await this.applyFix(file.path, result.fixed);
                     }
                     else {
                         await this.showDiffAndConfirm(file.path, file.content, result.fixed);
@@ -180,7 +171,7 @@ Return the complete modified file content:`,
             });
             // Apply or confirm
             if (options.apply) {
-                await this.applyFix(file.path, file.content, result.fixed);
+                await this.applyFix(file.path, result.fixed);
             }
             else {
                 await this.showDiffAndConfirm(file.path, file.content, result.fixed);
@@ -188,8 +179,7 @@ Return the complete modified file content:`,
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'FIX_FAILED' });
         }
     }
     extractCode(response, language) {
@@ -359,10 +349,9 @@ Return the complete modified file content:`,
         });
         console.log();
         // Confirm
-        const showDiffs = this.config.get('preferences').showDiffs;
         const autoApply = this.config.get('preferences').autoApplyFixes;
         if (autoApply) {
-            await this.applyFix(filePath, original, modified);
+            await this.applyFix(filePath, modified);
             return;
         }
         // Non-TTY: show the diff but don't try to prompt — re-run with --apply
@@ -384,7 +373,7 @@ Return the complete modified file content:`,
         ]);
         switch (action) {
             case 'apply':
-                await this.applyFix(filePath, original, modified);
+                await this.applyFix(filePath, modified);
                 break;
             case 'view':
                 this.showFullDiff(original, modified);
@@ -397,7 +386,7 @@ Return the complete modified file content:`,
                     },
                 ]);
                 if (confirm) {
-                    await this.applyFix(filePath, original, modified);
+                    await this.applyFix(filePath, modified);
                 }
                 break;
             case 'discard':
@@ -463,7 +452,7 @@ Return the complete modified file content:`,
         console.log(chalk.gray('─'.repeat(60)));
         console.log();
     }
-    async applyFix(filePath, original, modified) {
+    async applyFix(filePath, modified) {
         // Create backup
         const backup = this.fileUtils.backupFile(filePath);
         if (backup) {
@@ -474,7 +463,7 @@ Return the complete modified file content:`,
             this.logger.success(`Changes applied to ${filePath}`);
         }
         else {
-            this.logger.error('Failed to write changes');
+            throw new CliCommandError(`Failed to write changes to ${filePath}`, { code: 'FILE_WRITE_FAILED' });
         }
     }
 }

package/dist/commands/explain.js

@@ -5,8 +5,9 @@ import chalk from 'chalk';
 import { Marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
 import { createSpinner } from '../utils/logger.js';
-import { APIClient, CLIError, classifyError, formatCLIError } from '../utils/api.js';
+import { createAPIClient } from '../utils/api-client-factory.js';
 import { FileUtils } from '../utils/files.js';
+import { CliCommandError, commandFailure } from '../utils/command-contract.js';
 export class ExplainCommand {
     config;
     logger;
@@ -16,7 +17,7 @@ export class ExplainCommand {
     constructor(config, logger) {
         this.config = config;
         this.logger = logger;
-        this.api = new APIClient(config, logger);
+        this.api = createAPIClient(config, logger);
         this.fileUtils = new FileUtils(process.cwd(), config.get('project').ignorePatterns);
         this.marked = new Marked();
         this.marked.use(markedTerminal({
@@ -29,20 +30,17 @@ export class ExplainCommand {
     async run(filePath, options) {
         // Check auth
         if (!this.config.isAuthenticated()) {
-            this.logger.error('Not authenticated. Run: vigthoria login');
-            return;
+            throw new CliCommandError('Not authenticated. Run: vigthoria login', { code: 'AUTH_REQUIRED', category: 'authentication' });
         }
         // Server-side token validation — fail fast instead of waiting for 401
         const tokenCheck = await this.api.validateToken();
         if (!tokenCheck.valid) {
-            this.logger.error(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login');
-            return;
+            throw new CliCommandError(tokenCheck.error || 'Auth token is invalid. Run: vigthoria login', { code: 'AUTH_SESSION_INVALID', category: 'authentication' });
         }
         // Read file
         const file = this.fileUtils.readFile(filePath);
         if (!file) {
-            this.logger.error(`File not found: ${filePath}`);
-            return;
+            throw new CliCommandError(`File not found: ${filePath}`, { code: 'FILE_NOT_FOUND', category: 'configuration' });
         }
         // Get code to explain
         let codeToExplain = file.content;
@@ -80,8 +78,7 @@ export class ExplainCommand {
         }
         catch (error) {
             spinner.stop();
-            const cliErr = error instanceof CLIError ? error : classifyError(error);
-            this.logger.error(formatCLIError(cliErr));
+            throw commandFailure(error, { code: 'EXPLAIN_FAILED' });
         }
     }
     /**

package/dist/commands/fork.d.ts

@@ -7,8 +7,7 @@ interface ForkOptions {
 }
 export declare class ForkCommand {
     private config;
-    private logger;
-    constructor(config: Config, logger: Logger);
+    constructor(config: Config, _logger: Logger);
     private getHeaders;
     private getBaseUrl;
     private resolveWorkspaceRoot;

package/dist/commands/fork.js

@@ -1,17 +1,16 @@
-import { isServerRuntime } from '../utils/api.js';
+import { hasLocalV3AgentCapability } from '../utils/runtime-capability.js';
 /**
  * fork.ts — Fork from an existing V3 agent run and stream the result.
  */
 import chalk from 'chalk';
 import { createRequire } from 'node:module';
 import { createSpinner, CH } from '../utils/logger.js';
+import { CliCommandError, commandFailure, formatSuccessJson } from '../utils/command-contract.js';
 const require = createRequire(import.meta.url);
 export class ForkCommand {
     config;
-    logger;
-    constructor(config, logger) {
+    constructor(config, _logger) {
         this.config = config;
-        this.logger = logger;
     }
     getHeaders() {
         const headers = { 'Content-Type': 'application/json' };
@@ -29,7 +28,7 @@ export class ForkCommand {
     }
     getBaseUrl() {
         const configuredApiUrl = String(this.config.get('apiUrl') || 'https://coder.vigthoria.io').replace(/\/$/, '');
-        const allowLocal = isServerRuntime() && process.env.VIGTHORIA_ALLOW_LOCAL_V3_AGENT === '1';
+        const allowLocal = hasLocalV3AgentCapability();
         return (process.env.VIGTHORIA_V3_AGENT_URL ||
             process.env.V3_AGENT_URL ||
             (allowLocal ? 'http://127.0.0.1:8030' : null) ||
@@ -53,6 +52,13 @@ export class ForkCommand {
         const workspace = this.resolveWorkspaceRoot(project);
         const eventIndex = options.eventIndex || 0;
         const spinner = createSpinner(`Forking run ${runId}...`).start();
+        const streamController = new AbortController();
+        let interrupted = false;
+        const onInterrupt = () => {
+            interrupted = true;
+            streamController.abort();
+        };
+        process.once('SIGINT', onInterrupt);
         try {
             const baseUrl = this.getBaseUrl();
             const body = {
@@ -66,33 +72,57 @@ export class ForkCommand {
                 method: 'POST',
                 headers: this.getHeaders(),
                 body: JSON.stringify(body),
+                signal: streamController.signal,
             });
             if (!resp.ok) {
                 spinner.stop();
                 if (resp.status === 404) {
-                    this.logger.error(`Run ${runId} not found or has no event log.`);
+                    throw new CliCommandError(`Run ${runId} not found or has no event log.`, {
+                        code: 'RUN_NOT_FOUND', status: resp.status,
+                    });
                 }
                 else if (resp.status === 502 || resp.status === 503) {
-                    this.logger.error(`V3 run-history route is not available on ${baseUrl}. Backend may not expose /api/runs.`);
+                    throw new CliCommandError(`V3 run-history route is not available on ${baseUrl}. Backend may not expose /api/runs.`, {
+                        code: 'RUN_HISTORY_UNAVAILABLE', status: resp.status, category: 'network',
+                    });
                 }
                 else {
-                    this.logger.error(`Fork failed: ${resp.status} ${resp.statusText}`);
+                    throw new CliCommandError(`Fork failed: ${resp.status} ${resp.statusText}`, {
+                        code: 'RUN_FORK_FAILED', status: resp.status,
+                    });
                 }
-                return;
             }
             spinner.stop();
-            console.log(chalk.bold(`\n${CH.success} Forked from ${chalk.cyan(runId)} at event ${eventIndex}\n`));
+            if (!options.json)
+                console.log(chalk.bold(`\n${CH.success} Forked from ${chalk.cyan(runId)} at event ${eventIndex}\n`));
             if (!resp.body) {
-                this.logger.error('No response body');
-                return;
+                throw new CliCommandError('Fork response did not contain an event stream', { code: 'RUN_FORK_STREAM_MISSING' });
             }
             // Stream SSE events
             const reader = resp.body.getReader();
             const decoder = new TextDecoder();
             let buffer = '';
             let toolCallNum = 0;
-            while (true) {
-                const { done, value } = await reader.read();
+            let completed = false;
+            const events = [];
+            const configuredIdle = Number.parseInt(process.env.VIGTHORIA_FORK_IDLE_TIMEOUT_MS || '', 10);
+            const idleTimeoutMs = Number.isFinite(configuredIdle) && configuredIdle > 0 ? configuredIdle : 60_000;
+            stream: while (true) {
+                let timer;
+                const { done, value } = await Promise.race([
+                    reader.read(),
+                    new Promise((_resolve, reject) => {
+                        timer = setTimeout(() => {
+                            streamController.abort();
+                            reject(new CliCommandError(`Fork event stream was idle for ${idleTimeoutMs}ms.`, {
+                                code: 'RUN_FORK_IDLE_TIMEOUT', category: 'network',
+                            }));
+                        }, idleTimeoutMs);
+                    }),
+                ]).finally(() => {
+                    if (timer)
+                        clearTimeout(timer);
+                });
                 if (done)
                     break;
                 buffer += decoder.decode(value, { stream: true });
@@ -103,14 +133,14 @@ export class ForkCommand {
                         continue;
                     const payload = line.slice(6).trim();
                     if (payload === '[DONE]') {
-                        console.log(chalk.bold(`\n${CH.success} Fork run complete\n`));
-                        return;
+                        completed = true;
+                        break stream;
                     }
                     try {
                         const evt = JSON.parse(payload);
                         const type = evt.type || 'unknown';
+                        events.push(evt);
                         if (options.json) {
-                            console.log(JSON.stringify(evt));
                             continue;
                         }
                         switch (type) {
@@ -144,21 +174,41 @@ export class ForkCommand {
                                 break;
                             }
                             case 'error':
-                                console.log(chalk.red(`  ❌ ERROR: `) + (evt.message || '').substring(0, 200));
-                                break;
+                                throw new CliCommandError(String(evt.message || 'Fork stream reported an error.'), {
+                                    code: 'RUN_FORK_STREAM_ERROR', details: evt,
+                                });
                             default:
                                 console.log(chalk.dim(`  ${type}: ${JSON.stringify(evt).substring(0, 80)}`));
                         }
                     }
-                    catch {
-                        // skip unparseable lines
+                    catch (error) {
+                        if (error instanceof CliCommandError)
+                            throw error;
+                        throw new CliCommandError('Fork event stream contained malformed JSON.', {
+                            code: 'RUN_FORK_STREAM_MALFORMED', details: { payload: payload.slice(0, 200) }, cause: error,
+                        });
                     }
                 }
             }
+            if (!completed) {
+                throw new CliCommandError('Fork event stream ended without a completion marker.', { code: 'RUN_FORK_STREAM_INCOMPLETE' });
+            }
+            if (options.json) {
+                console.log(formatSuccessJson('fork', { runId, eventIndex, events }, { stream: true, eventCount: events.length }));
+            }
+            else {
+                console.log(chalk.bold(`\n${CH.success} Fork run complete\n`));
+            }
         }
         catch (err) {
             spinner.stop();
-            this.logger.error(`Fork error: ${err.message}`);
+            if (interrupted) {
+                throw new CliCommandError('Fork cancelled by user.', { code: 'RUN_FORK_CANCELLED', category: 'cancelled', cause: err });
+            }
+            throw commandFailure(err, { code: 'RUN_FORK_FAILED' });
+        }
+        finally {
+            process.removeListener('SIGINT', onInterrupt);
         }
     }
 }

package/dist/commands/game.d.ts

@@ -18,7 +18,7 @@ export declare class GameCommand {
     }): Promise<void>;
     validate(o: CommonOptions & {
         json?: boolean;
-    }): Promise<boolean>;
+    }): Promise<true>;
     private project;
     private sources;
     private finish;