@nomos-arc/arc 0.1.0

package/src/commands/init.ts

@@ -0,0 +1,121 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { GitAdapter } from '../adapters/git.js';
+import { createLogger } from '../core/logger.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerInitCommand(program: Command): void {
+  program
+    .command('init [task]')
+    .description('Initialize a new project (no task) or a new task (with task name)')
+    .option('--force', 'Force re-initialize: prune zombie worktrees, delete task branch, and reset state')
+    .action(async (task?: string, options?: { force?: boolean }) => {
+      try {
+        if (!task) {
+          // Project initialization — no config exists yet
+          const { orchestrator } = await createOrchestrator({ skipConfig: true });
+          await orchestrator.initProject();
+          console.log(
+            "Project initialized. Next steps:\n" +
+            "  1. Edit tasks-management/rules/global.md with your engineering standards.\n" +
+            "  2. Run: arc init <task-name> to create your first task."
+          );
+        } else if (options?.force) {
+          // Force Recovery — zombie worktree cleanup + state reset
+          // GAP-3 fix: handles SIGKILL mid-init, crash mid-worktree-creation,
+          // or any state where git metadata and filesystem are out of sync.
+          //
+          // RT2-6.1 fix: The previous 5-step sequence had a fatal ordering bug.
+          // Step 1 was `git worktree prune`, which only removes metadata for worktrees
+          // whose directories NO LONGER EXIST. In the most common crash scenario
+          // (SIGKILL mid-creation), the directory STILL EXISTS, so prune is a no-op.
+          // Then branch deletion fails because git says the branch is "checked out"
+          // in the still-registered worktree.
+          //
+          // Correct sequence: unlock → remove directory → prune metadata → delete branch.
+          const { orchestrator, config, projectRoot } = await createOrchestrator();
+          // RT2-6.1 fix: Use GitAdapter (already imported via factory), not raw simpleGit.
+          // The previous code called `simpleGit(projectRoot)` but simpleGit was never
+          // imported in init.ts — a compile-time error hidden by the --help verification.
+          const gitAdapter = new GitAdapter(projectRoot, config,
+            createLogger(config.logging.level));
+
+          const branchName = `${config.execution.shadow_branch_prefix}${task}`;
+          const worktreePath = path.join(
+            config.execution.worktree_base,
+            path.basename(projectRoot),
+            task,
+          );
+
+          // Step 1: Unlock the worktree if it was locked (prevents removal)
+          try {
+            await gitAdapter.raw(['worktree', 'unlock', worktreePath]);
+          } catch {
+            // Worktree may not exist or not be locked — not an error
+          }
+
+          // Step 2: Remove the worktree directory from filesystem
+          // This MUST happen before prune — prune only cleans metadata for
+          // directories that no longer exist on disk.
+          if (fs.existsSync(worktreePath)) {
+            fs.rmSync(worktreePath, { recursive: true, force: true });
+          }
+
+          // Step 3: Prune git worktree metadata (now that directory is gone)
+          await gitAdapter.raw(['worktree', 'prune']);
+
+          // Step 4: Force-delete the task's shadow branch
+          // This now succeeds because the worktree referencing it was pruned.
+          try {
+            await gitAdapter.raw(['branch', '-D', branchName]);
+          } catch {
+            // Branch may not exist — not an error
+          }
+
+          // Step 5: Remove stale state file
+          const statePath = path.join(projectRoot, 'tasks-management', 'state', `${task}.json`);
+          if (fs.existsSync(statePath)) {
+            fs.rmSync(statePath);
+          }
+
+          // Step 6: Re-initialize the task cleanly
+          await orchestrator.initTask(task);
+          console.log(
+            `[nomos:force] Zombie worktree and stale state cleared for '${task}'.\n` +
+            `Task re-initialized.\n` +
+            `  Edit: tasks-management/tasks/${task}.md\n` +
+            `  Then: arc plan ${task}`
+          );
+        } else {
+          // Task initialization — config MUST exist.
+          // RTV-8: If config is missing, loadConfig() throws NomosError('config_not_found').
+          // The error handler below catches this and provides a targeted recovery message.
+          const { orchestrator } = await createOrchestrator();
+          await orchestrator.initTask(task);
+          console.log(
+            `Task '${task}' initialized.\n` +
+            `  Edit: tasks-management/tasks/${task}.md\n` +
+            `  Then: arc plan ${task}`
+          );
+        }
+      } catch (err) {
+        if (err instanceof NomosError) {
+          if (err.code === 'config_not_found') {
+            // RTV-8 fix: specific message when arc init <task> is run without a project
+            console.error(
+              `[nomos:error] No project found. To create a task, you must first initialize a project.\n` +
+              `  Run: arc init   (to scaffold a new project in the current directory)\n` +
+              `  Then: arc init ${task}`
+            );
+          } else {
+            console.error(`[nomos:error] ${err.message}`);
+          }
+          process.exit(1);
+        }
+        console.error(`[nomos:error] Unexpected error: ${err}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/list.ts

@@ -0,0 +1,75 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerListCommand(program: Command): void {
+  program
+    .command('list')
+    .description('List all tasks and their current status')
+    .action(async () => {
+      try {
+        const { orchestrator } = await createOrchestrator();
+        const tasks = await orchestrator.listTasks();
+
+        if (tasks.length === 0) {
+          console.log('No tasks found. Run: arc init <task-name> to create one.');
+          process.exit(0);
+        }
+
+        // Column widths
+        const COL_TASK    = 16;
+        const COL_STATUS  = 14;
+        const COL_VERSION = 7;
+        const COL_SCORE   = 10;
+        const COL_TOKENS  = 6;
+
+        const pad = (s: string, n: number): string => s.padEnd(n);
+
+        const header =
+          pad('Task', COL_TASK) +
+          pad('Status', COL_STATUS) +
+          pad('Version', COL_VERSION) +
+          pad('Last Score', COL_SCORE) +
+          'Tokens';
+
+        const divider =
+          '─'.repeat(COL_TASK - 1) + '  ' +
+          '─'.repeat(COL_STATUS - 1) + '  ' +
+          '─'.repeat(COL_VERSION - 1) + '  ' +
+          '─'.repeat(COL_SCORE - 1) + '  ' +
+          '─'.repeat(COL_TOKENS);
+
+        console.log(header);
+        console.log(divider);
+
+        for (const task of tasks) {
+          const lastReview = task.history
+            .slice()
+            .reverse()
+            .find(h => h.review !== null)?.review;
+
+          const score = lastReview?.score != null
+            ? lastReview.score.toFixed(2)
+            : 'N/A';
+
+          const row =
+            pad(task.task_id, COL_TASK) +
+            pad(task.meta.status, COL_STATUS) +
+            pad(String(task.current_version), COL_VERSION) +
+            pad(score, COL_SCORE) +
+            String(task.budget.tokens_used);
+
+          console.log(row);
+        }
+
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/map.ts

@@ -0,0 +1,55 @@
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import { loadConfig } from '../core/config.js';
+import { createLogger } from '../core/logger.js';
+import { MapPipeline } from '../core/graph/pipeline.js';
+import { AuthManager } from '../core/auth/manager.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerMapCommand(program: Command): void {
+  program
+    .command('map [patterns...]')
+    .description('Scan project files and build a semantic dependency map')
+    .option('--no-ai', 'Skip AI enrichment (structural map only)')
+    .option('--force', 'Re-parse all files even if unchanged')
+    .action(async (patterns: string[], opts: { ai: boolean; force: boolean }) => {
+      try {
+        const { config, projectRoot } = loadConfig();
+
+        // --no-ai flag disables enrichment for this run only
+        if (!opts.ai) {
+          config.graph.ai_enrichment = false;
+        }
+
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+        const logger = createLogger(config.logging.level, logDir);
+
+        const authManager = new AuthManager(config.auth, logger);
+        const pipeline = new MapPipeline(config, projectRoot, logger, authManager);
+
+        const result = await pipeline.run({
+          noAi: !opts.ai,
+          force: opts.force ?? false,
+          patterns: patterns.length > 0 ? patterns : undefined,
+        });
+
+        const { total_files, structural_only, semantically_enriched, indexed } = result.map.stats;
+
+        console.error(`[nomos:info] Map complete.`);
+        console.log(`Mapped ${total_files} files: ${structural_only} structural, ${semantically_enriched} semantic, ${indexed} indexed`);
+
+        // [AMB-6 FIX] Exit codes: 0 = success, 1 = fatal, 10 = partial AI failure (NOT 2)
+        if (result.aiFailures > 0) {
+          process.exit(10);
+        }
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/plan.ts

@@ -0,0 +1,30 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+import type { ExecutionMode } from '../types/index.js';
+
+export function registerPlanCommand(program: Command): void {
+  program
+    .command('plan <task>')
+    .description('Run the planner for a task and save the resulting plan')
+    .option('--mode <mode>', 'Execution mode: supervised or dry-run')
+    .action(async (task: string, options: { mode?: string }) => {
+      try {
+        const { orchestrator, config } = await createOrchestrator();
+
+        // Resolve mode: flag > config.execution.default_mode
+        const mode: ExecutionMode = (options.mode as ExecutionMode) ?? config.execution.default_mode;
+
+        const state = await orchestrator.plan(task, mode);
+        const version = state.current_version;
+        console.log(`Plan v${version} saved to tasks-management/plans/${task}-v${version}.diff`);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/review.ts

@@ -0,0 +1,58 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+import type { ExecutionMode } from '../types/index.js';
+
+export function registerReviewCommand(program: Command): void {
+  program
+    .command('review <task>')
+    .description('Run the reviewer for a task and record the review result')
+    .option('--mode <mode>', 'Execution mode: supervised or dry-run')
+    .action(async (task: string, options: { mode?: string }) => {
+      try {
+        const { orchestrator, config } = await createOrchestrator();
+
+        // Resolve mode: flag > config.execution.default_mode
+        const mode: ExecutionMode = (options.mode as ExecutionMode) ?? config.execution.default_mode;
+
+        // M-7 fix: exit codes derived from state inspection, NOT exception catching.
+        // orchestrator.review() returns state and never throws on review outcomes.
+        const state = await orchestrator.review(task, mode);
+        const lastReview = state.history[state.history.length - 1]?.review;
+
+        if (lastReview) {
+          const version = state.current_version;
+          const score = lastReview.score;
+          const status = state.meta.status;
+          const issues = lastReview.issues ?? [];
+          const highCount = issues.filter(i => i.severity === 'high').length;
+          const medCount = issues.filter(i => i.severity === 'medium').length;
+          const lowCount = issues.filter(i => i.severity === 'low').length;
+          const summary = lastReview.summary ?? '';
+
+          console.log(
+            `Review complete (v${version}):\n` +
+            `  Score: ${score}\n` +
+            `  Status: ${status}\n` +
+            `  Issues: ${issues.length} (${highCount} high, ${medCount} medium, ${lowCount} low)\n` +
+            `  Summary: ${summary}`
+          );
+        }
+
+        if (state.meta.status === 'approved') {
+          process.exit(0);
+        } else if (state.meta.status === 'refinement') {
+          process.exit(2);  // expected non-success — not an error
+        } else {
+          process.exit(1);  // failed, or other unexpected state
+        }
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/run.ts

@@ -0,0 +1,63 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+import type { ExecutionMode } from '../types/index.js';
+
+export function registerRunCommand(program: Command): void {
+  program
+    .command('run <task>')
+    .description('Run full plan/review cycle until convergence or max iterations')
+    .option('--mode <mode>', 'Execution mode: supervised or dry-run')
+    .option('--iterations <n>', 'Maximum number of plan/review iterations', parseInt)
+    .action(async (task: string, options: { mode?: string; iterations?: number }) => {
+      try {
+        const { orchestrator, config } = await createOrchestrator();
+
+        // Resolve mode: flag > config.execution.default_mode
+        const mode: ExecutionMode = (options.mode as ExecutionMode) ?? config.execution.default_mode;
+        const iterations = options.iterations;
+
+        // RTV-6 fix: exit code determination via meta.approval_reason inspection.
+        // NomosError('convergence_failed') is NOT thrown anywhere — this is the M-7 pattern
+        // applied to run: state inspection, not exception catching.
+        const finalState = await orchestrator.run(task, mode, iterations);
+
+        const lastEntry = finalState.history[finalState.history.length - 1];
+        const lastScore = lastEntry?.review?.score ?? 'N/A';
+        const version = finalState.current_version;
+        const status = finalState.meta.status;
+        const tokensUsed = finalState.budget.tokens_used;
+        const estimatedCost = finalState.budget.estimated_cost_usd.toFixed(4);
+
+        console.log(
+          `Run complete (v${version}):\n` +
+          `  Status: ${status}\n` +
+          `  Final score: ${lastScore}\n` +
+          `  Tokens used: ${tokensUsed}\n` +
+          `  Estimated cost: $${estimatedCost}`
+        );
+
+        if (finalState.meta.status === 'approved') {
+          if (finalState.meta.approval_reason === 'max_iterations_reached') {
+            // Converged by iteration limit, not by score threshold — signal as non-convergence
+            console.error(
+              `[nomos:warn] Max iterations reached without meeting score threshold. ` +
+              `Final score: ${lastScore}. ` +
+              `Consider increasing max_iterations or adjusting score_threshold in config.`
+            );
+            process.exit(2);  // expected non-convergence
+          }
+          process.exit(0);  // genuine convergence
+        } else {
+          process.exit(1);  // error (failed state, budget exceeded, etc.)
+        }
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/search.ts

@@ -0,0 +1,147 @@
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import type { Command } from 'commander';
+import { loadConfig } from '../core/config.js';
+import { createLogger } from '../core/logger.js';
+import { NomosError } from '../core/errors.js';
+import { QueryEngine } from '../search/query-engine.js';
+import { AuthManager } from '../core/auth/manager.js';
+import type { SearchResult } from '../types/index.js';
+
+export function registerSearchCommand(program: Command): void {
+  program
+    .command('search <query>')
+    .description('Semantically search the codebase using the vector index')
+    .option('--top <n>', 'Maximum number of results', (v) => parseInt(v, 10), 5)
+    .option('--threshold <score>', 'Minimum similarity score (0.0–1.0)', (v) => parseFloat(v), 0.7)
+    .option('--json', 'Output raw JSON instead of formatted table')
+    .action(async (query: string, opts: { top: number; threshold: number; json?: boolean }) => {
+      try {
+        if (!query.trim()) {
+          console.error('Usage: arc search <query> [--top <n>] [--threshold <score>] [--json]');
+          process.exit(1);
+        }
+
+        const { config, projectRoot } = loadConfig();
+        const logDir = path.join(projectRoot, 'tasks-management', 'logs');
+
+        // In --json mode: suppress info/warn output to keep stdout machine-parseable [S-5]
+        const logLevel = opts.json ? 'error' : config.logging.level;
+        const logger = createLogger(logLevel, opts.json ? undefined : logDir);
+
+        const authManager = new AuthManager(config.auth, logger);
+        const engine = new QueryEngine(projectRoot, config, logger, authManager);
+
+        let results: SearchResult[];
+        try {
+          results = await engine.search(query, { topK: opts.top, threshold: opts.threshold });
+        } catch (err) {
+          if (err instanceof NomosError && err.code === 'search_index_not_found') {
+            if (opts.json) {
+              console.error(`[nomos:error] ${err.message}`);
+            } else {
+              console.error(`[nomos:error] ${err.message}`);
+              console.error('Run: arc map');
+            }
+            process.exit(1);
+          }
+          throw err;
+        }
+
+        if (opts.json) {
+          // Read index age from metadata (best-effort) [S-5]
+          let indexAge: string | null = null;
+          try {
+            const metaPath = path.join(config.search.vector_store_path, 'index-meta.json');
+            const raw = await fs.readFile(metaPath, 'utf-8');
+            const meta = JSON.parse(raw) as { last_full_index: string };
+            indexAge = meta.last_full_index;
+          } catch { /* non-fatal */ }
+
+          // Verify no vector field leaks [S-5] — SearchResult type excludes it by design
+          const output = {
+            query,
+            results: results.map((r) => ({
+              id: r.id,
+              type: r.type,
+              file_path: r.file_path,
+              symbol_name: r.symbol_name,
+              symbol_type: r.symbol_type,
+              line_start: r.line_start,
+              line_end: r.line_end,
+              purpose: r.purpose,
+              similarity_score: r.similarity_score,
+              graph_depth: r.graph_depth,
+              dependents_count: r.dependents_count,
+              is_core_module: r.is_core_module,
+              is_stale: r.is_stale,
+            })),
+            metadata: {
+              top_k: opts.top,
+              threshold: opts.threshold,
+              total_results: results.length,
+              index_age: indexAge,
+            },
+          };
+          console.log(JSON.stringify(output, null, 2));
+          process.exit(0);
+        }
+
+        // Human-readable output
+        if (results.length === 0) {
+          console.log(`No results found above threshold ${opts.threshold.toFixed(2)}.`);
+          process.exit(0);
+        }
+
+        console.log(`\nResults for: "${query}"\n`);
+
+        for (let i = 0; i < results.length; i++) {
+          const r = results[i]!;
+          const rank = i + 1;
+          const score = `[${r.similarity_score.toFixed(2)}]`;
+
+          // Header line: file + optional symbol + score + optional line range
+          let header = `  ${rank}. ${r.file_path}`;
+          if (r.symbol_name) {
+            const symbolSig = r.symbol_type ? `${r.symbol_name}()` : r.symbol_name;
+            header += ` :: ${symbolSig}`;
+          }
+          // Pad score to column 60
+          const headerPad = header.length < 60 ? ' '.repeat(60 - header.length) : '  ';
+          header += `${headerPad}${score}`;
+          if (r.line_start !== null && r.line_end !== null) {
+            header += `  L${r.line_start}-${r.line_end}`;
+          }
+          console.log(header);
+
+          // Purpose line
+          console.log(`     "${r.purpose}"`);
+
+          // Depth / stale line [TRAP-4]: never print graph_depth === -1 numerically
+          if (r.is_stale) {
+            console.log(`     ⚠ Stale — file removed since last index. Run: arc index --incremental`);
+          } else if (r.is_core_module) {
+            console.log(
+              `     ⚠ Core Module (depth ${r.graph_depth}) — modifying this affects ${r.dependents_count} dependents`,
+            );
+          } else {
+            console.log(
+              `     Leaf Module (depth ${r.graph_depth}) — ${r.dependents_count} dependents`,
+            );
+          }
+
+          if (i < results.length - 1) console.log('');
+        }
+
+        console.log(`\nFound ${results.length} results (threshold: ${opts.threshold.toFixed(2)}, top: ${opts.top})`);
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/show.ts

@@ -0,0 +1,63 @@
+import * as path from 'node:path';
+import * as fs from 'node:fs/promises';
+import type { Command } from 'commander';
+import { loadConfig } from '../core/config.js';
+import { readProjectMap, migrateProjectMap } from '../core/graph/map-schema.js';
+import { MapRenderer } from '../core/graph/renderer.js';
+import { generateHtml } from '../core/graph/html-template.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerShowCommand(program: Command): void {
+  const show = program
+    .command('show')
+    .description('Display visual outputs');
+
+  show
+    .command('map')
+    .description('Open the interactive dependency graph in your browser')
+    .option('--no-open', 'Generate index.html without opening browser')
+    .action(async (opts: { open: boolean }) => {
+      try {
+        const { config, projectRoot } = loadConfig();
+
+        const outputDir = path.resolve(projectRoot, config.graph.output_dir);
+        const mapPath = path.join(outputDir, 'project_map.json');
+
+        const rawMap = await readProjectMap(mapPath);
+        if (rawMap === null) {
+          console.error('[nomos:error] No project map found. Run: arc map first.');
+          process.exit(1);
+        }
+
+        const map = migrateProjectMap(rawMap);
+        const renderer = new MapRenderer();
+        const { nodes, edges } = renderer.render(map);
+
+        const html = generateHtml(
+          JSON.stringify(map),
+          JSON.stringify(nodes),
+          JSON.stringify(edges),
+        );
+
+        const htmlPath = path.join(outputDir, 'index.html');
+        await fs.mkdir(outputDir, { recursive: true });
+        await fs.writeFile(htmlPath, html, 'utf-8');
+
+        console.log(`Graph visualization written to: ${htmlPath}`);
+
+        if (opts.open !== false) {
+          const { default: open } = await import('open');
+          await open(htmlPath);
+        }
+
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}

package/src/commands/status.ts

@@ -0,0 +1,59 @@
+import type { Command } from 'commander';
+import { createOrchestrator } from '../core/factory.js';
+import { NomosError } from '../core/errors.js';
+
+export function registerStatusCommand(program: Command): void {
+  program
+    .command('status <task>')
+    .description('Show current status and metadata for a task')
+    .action(async (task: string) => {
+      try {
+        const { orchestrator } = await createOrchestrator();
+        const state = await orchestrator.status(task);
+
+        // RTV-4 fix: derive hasMeteredTokens from history entries — never from an undeclared variable
+        const hasMeteredTokens = state.history.some(h => h.tokens_source === 'metered');
+        const lastReview = state.history
+          .slice()
+          .reverse()
+          .find(h => h.review !== null)?.review;
+
+        console.log(
+          `Task:            ${state.task_id}\n` +
+          `Status:          ${state.meta.status}\n` +
+          `Version:         ${state.current_version}\n` +
+          `Last Score:      ${lastReview?.score?.toFixed(2) ?? 'N/A'}\n` +
+          `Shadow Branch:   ${state.shadow_branch.branch}\n` +
+          `Worktree:        ${state.shadow_branch.worktree}\n` +
+          `Tokens Used:     ${state.budget.tokens_used} (${hasMeteredTokens ? 'metered' : '~estimated'})\n` +
+          `Estimated Cost:  $${state.budget.estimated_cost_usd.toFixed(4)}`
+        );
+
+        // RTV-7 fix: recovery hint for every non-terminal status
+        const recoveryHints: Partial<Record<typeof state.meta.status, string>> = {
+          init:           `Run: arc plan ${task}`,
+          planning:       `(in progress — if stuck, run: arc discard ${task} && arc init ${task})`,
+          pending_review: `Run: arc review ${task}`,
+          reviewing:      `(in progress — if stuck, run: arc discard ${task} && arc init ${task})`,
+          refinement:     `Run: arc plan ${task}  (to address review feedback)`,
+          approved:       `Run: arc apply ${task}  (to merge) or: arc discard ${task}`,
+          merge_conflict: `Resolve conflicts manually, then: arc apply ${task}`,
+          stalled:        `Run: arc plan ${task}  (to retry from stalled state)`,
+          failed:         `Run: arc plan ${task}  (to retry from failed state)`,
+          merged:         `(terminal — task complete)`,
+          discarded:      `(terminal — task discarded)`,
+        };
+        const hint = recoveryHints[state.meta.status];
+        if (hint) console.log(`\nNext step: ${hint}`);
+
+        process.exit(0);
+      } catch (err) {
+        if (err instanceof NomosError) {
+          console.error(`[nomos:error] ${err.message}`);
+        } else {
+          console.error(`[nomos:error] Unexpected error: ${err}`);
+        }
+        process.exit(1);
+      }
+    });
+}