orbital-command 0.2.0 → 1.0.0

package/server/utils/dispatch-utils.ts

@@ -1,11 +1,11 @@
 import type Database from 'better-sqlite3';
-import type { Server } from 'socket.io';
+import type { Emitter } from '../project-emitter.js';
 import type { ScopeService } from '../services/scope-service.js';
 import type { WorkflowEngine } from '../../shared/workflow-engine.js';
 import { isSessionPidAlive } from './terminal-launcher.js';
 import { createLogger } from './logger.js';
 
-const log = createLogger('dispatch');
+const log = createLogger('dispatch-utils');
 
 interface DispatchRow {
   data: string;
@@ -15,7 +15,7 @@ interface DispatchRow {
 /** Mark a DISPATCH event as resolved and emit socket notification. */
 export function resolveDispatchEvent(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   eventId: string,
   outcome: 'completed' | 'failed' | 'abandoned',
   error?: string,
@@ -42,10 +42,73 @@ export function resolveDispatchEvent(
   });
 }
 
+/** Auto-revert scope status when a dispatch is abandoned, if the forward edge
+ *  has autoRevert=true and the scope is still at the dispatch target.
+ *  Safe: only reverts if the scope hasn't been moved since the dispatch.
+ *  Returns true if revert was successful. */
+function autoRevertAbandonedScope(
+  scopeService: ScopeService,
+  engine: WorkflowEngine,
+  scopeId: number,
+  data: Record<string, unknown>,
+): boolean {
+  try {
+    const transition = data.transition as { from: string; to: string } | null;
+    if (!transition?.from || !transition?.to) return false;
+
+    const scope = scopeService.getById(scopeId);
+    // Only revert if scope is still at the dispatch target (hasn't been moved)
+    if (!scope || scope.status !== transition.to) return false;
+
+    const edge = engine.findEdge(transition.from, transition.to);
+    if (!edge?.autoRevert) return false;
+
+    const result = scopeService.updateStatus(scopeId, transition.from, 'rollback');
+    if (!result.ok) return false;
+    log.info('Auto-reverted abandoned dispatch', {
+      scopeId, from: transition.to, to: transition.from,
+    });
+    return true;
+  } catch (err) {
+    log.error('Auto-revert failed', { scopeId, error: String(err) });
+    return false;
+  }
+}
+
+/** Attempt auto-revert for an abandoned dispatch and clear the abandoned state if successful.
+ *  Loads the dispatch event data, tries auto-revert, and re-resolves as 'completed' if the
+ *  scope was successfully reverted. Returns true if auto-revert + clear succeeded. */
+export function tryAutoRevertAndClear(
+  db: Database.Database,
+  io: Emitter,
+  scopeService: ScopeService,
+  engine: WorkflowEngine,
+  eventId: string,
+): boolean {
+  const row = db.prepare('SELECT data, scope_id FROM events WHERE id = ?')
+    .get(eventId) as DispatchRow | undefined;
+  if (!row || row.scope_id == null) return false;
+
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(row.data);
+  } catch {
+    return false;
+  }
+
+  const reverted = autoRevertAbandonedScope(scopeService, engine, row.scope_id, data);
+  if (reverted) {
+    // Clear the abandoned state so getAbandonedScopeIds won't return this scope
+    resolveDispatchEvent(db, io, eventId, 'completed');
+    log.info('Cleared abandoned dispatch after auto-revert', { eventId, scope_id: row.scope_id });
+  }
+  return reverted;
+}
+
 /** Resolve all unresolved DISPATCH events for a given scope */
 export function resolveActiveDispatchesForScope(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   scopeId: number,
   outcome: 'completed' | 'failed' | 'abandoned',
 ): void {
@@ -63,7 +126,7 @@ export function resolveActiveDispatchesForScope(
  *  Used by both recover and dismiss-abandoned routes to clear abandoned state. */
 export function resolveAbandonedDispatchesForScope(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   scopeId: number,
 ): number {
   const rows = db.prepare(
@@ -104,15 +167,13 @@ export function linkPidToDispatch(
 /** Resolve all unresolved DISPATCH events linked to a specific PID.
  *  Called when a SESSION_END event is received, indicating the Claude session
  *  process has exited and its dispatches should be cleared.
- *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target (e.g. "implementing") after completion.
- *  Reverting on session end was destroying completed work and deleting scope files. */
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
 export function resolveDispatchesByPid(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   pid: number,
-): number {
+  outcome: 'completed' | 'abandoned' = 'abandoned',
+): string[] {
   const rows = db.prepare(
     `SELECT id FROM events
      WHERE type = 'DISPATCH'
@@ -121,38 +182,39 @@ export function resolveDispatchesByPid(
   ).all(pid) as Array<{ id: string }>;
 
   for (const row of rows) {
-    resolveDispatchEvent(db, io, row.id, 'abandoned');
+    resolveDispatchEvent(db, io, row.id, outcome);
   }
 
-  return rows.length;
+  return rows.map(r => r.id);
 }
 
 /** Resolve all unresolved DISPATCH events linked to a specific dispatch ID.
  *  Called when a SESSION_END event includes dispatch_id from ORBITAL_DISPATCH_ID env var.
- *  Defaults to 'abandoned' — successful completions emit AGENT_COMPLETED first
- *  which resolves via inferScopeStatus as 'completed'. */
+ *  Outcome depends on how the session ended: normal_exit → completed, otherwise → abandoned.
+ *  Returns the resolved event IDs so callers can attempt auto-revert. */
 export function resolveDispatchesByDispatchId(
   db: Database.Database,
-  io: Server,
+  io: Emitter,
   dispatchId: string,
-): number {
+  outcome: 'completed' | 'abandoned' = 'abandoned',
+): string[] {
   const row = db.prepare(
     `SELECT id FROM events
      WHERE id = ? AND type = 'DISPATCH' AND JSON_EXTRACT(data, '$.resolved') IS NULL`,
   ).get(dispatchId) as { id: string } | undefined;
 
-  if (!row) return 0;
-  resolveDispatchEvent(db, io, row.id, 'abandoned');
-  return 1;
+  if (!row) return [];
+  resolveDispatchEvent(db, io, row.id, outcome);
+  return [row.id];
 }
 
-/** Fallback age threshold for dispatches without a linked PID (30 minutes). */
-const STALE_AGE_MS = 30 * 60 * 1000;
+/** Default fallback age threshold for dispatches without a linked PID (10 minutes). */
+const DEFAULT_STALE_AGE_MS = 10 * 60 * 1000;
 
 /** Get all scope IDs that have actively running DISPATCH events.
  *  Uses PID liveness (process.kill(pid, 0)) when available, falls back to
  *  age-based heuristic for legacy dispatches without a linked PID. */
-export function getActiveScopeIds(db: Database.Database, scopeService: ScopeService, engine: WorkflowEngine): number[] {
+export function getActiveScopeIds(db: Database.Database, scopeService: ScopeService, engine: WorkflowEngine, staleTimeoutMinutes?: number): number[] {
   const rows = db.prepare(
     `SELECT scope_id, data FROM events
      WHERE type = 'DISPATCH'
@@ -160,7 +222,8 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
        AND JSON_EXTRACT(data, '$.resolved') IS NULL`,
   ).all() as Array<{ scope_id: number; data: string }>;
 
-  const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+  const staleMs = staleTimeoutMinutes != null ? staleTimeoutMinutes * 60 * 1000 : DEFAULT_STALE_AGE_MS;
+  const cutoff = new Date(Date.now() - staleMs).toISOString();
   const active = new Set<number>();
 
   for (const row of rows) {
@@ -209,6 +272,7 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
     try {
       batchData = JSON.parse(batchRow.data);
     } catch {
+      log.warn('Skipping unparseable batch dispatch event data', { data: batchRow.data });
       continue;
     }
 
@@ -242,12 +306,14 @@ export function getActiveScopeIds(db: Database.Database, scopeService: ScopeServ
  *  3. No linked PID and dispatch older than STALE_AGE_MS (fallback)
  *  Called once at startup and periodically to clean up unresolved dispatches.
  *
- *  NOTE: Does NOT revert scope status. Skills like /scope-implement intentionally
- *  keep scopes at the transition target after completion. Auto-reverting was
- *  destroying completed work and deleting scope files. Users can manually
- *  move scopes back from the dashboard if needed. */
-export function resolveStaleDispatches(db: Database.Database, io: Server, scopeService: ScopeService, engine: WorkflowEngine): number {
-  const cutoff = new Date(Date.now() - STALE_AGE_MS).toISOString();
+ *  When a dispatch is abandoned, auto-reverts scope status if the forward edge
+ *  has autoRevert=true AND the scope is still at the dispatch target. This allows
+ *  safe recovery for edges like backlog→implementing where the session crashed
+ *  before doing meaningful work. Edges without autoRevert leave the scope in place
+ *  for manual recovery from the dashboard. */
+export function resolveStaleDispatches(db: Database.Database, io: Emitter, scopeService: ScopeService, engine: WorkflowEngine, staleTimeoutMinutes?: number): number {
+  const staleMs = staleTimeoutMinutes != null ? staleTimeoutMinutes * 60 * 1000 : DEFAULT_STALE_AGE_MS;
+  const cutoff = new Date(Date.now() - staleMs).toISOString();
 
   // Single query on events only — split by cache status
   const rows = db.prepare(
@@ -288,6 +354,8 @@ export function resolveStaleDispatches(db: Database.Database, io: Server, scopeS
 
     if (isStale) {
       resolveDispatchEvent(db, io, row.id, 'abandoned');
+      // Try auto-revert; if successful, clear the abandoned state
+      tryAutoRevertAndClear(db, io, scopeService, engine, row.id);
       resolved++;
     }
   }
@@ -306,6 +374,7 @@ export function resolveStaleDispatches(db: Database.Database, io: Server, scopeS
     try {
       batchData = JSON.parse(batchRow.data);
     } catch {
+      log.warn('Skipping unparseable batch dispatch event data', { eventId: batchRow.id });
       continue;
     }
 
@@ -388,6 +457,9 @@ export function getAbandonedScopeIds(
     const fromStatus = transition?.from as string ?? null;
     const abandonedAt = resolved?.at as string ?? row.timestamp;
 
+    // Defense-in-depth: skip scopes already at their pre-dispatch status (already reverted)
+    if (fromStatus && scope.status === fromStatus) continue;
+
     result.push({ scope_id: row.scope_id, from_status: fromStatus, abandoned_at: abandonedAt });
   }
 

package/server/utils/flag-builder.ts

@@ -0,0 +1,56 @@
+import type { DispatchFlags } from '../../shared/api-types.js';
+import { VALID_OUTPUT_FORMATS, validateToolName, validateEnvKey } from '../../shared/api-types.js';
+import { shellQuote } from './terminal-launcher.js';
+
+/**
+ * Compile a structured DispatchFlags object into a CLI flags string
+ * for the `claude` command. All parameterized values are validated
+ * and shell-quoted to prevent injection.
+ */
+export function buildClaudeFlags(flags: DispatchFlags): string {
+  const parts: string[] = [];
+
+  // Permission mode — 'default' means no flag (use Claude's built-in default)
+  if (flags.permissionMode === 'bypass') {
+    parts.push('--dangerously-skip-permissions');
+  } else if (flags.permissionMode && flags.permissionMode !== 'default') {
+    parts.push('--permission-mode', flags.permissionMode);
+  }
+
+  if (flags.verbose) parts.push('--verbose');
+  if (flags.noMarkdown) parts.push('--no-markdown');
+  if (flags.printMode) parts.push('-p');
+
+  if (flags.outputFormat && VALID_OUTPUT_FORMATS.includes(flags.outputFormat)) {
+    parts.push('--output-format', flags.outputFormat);
+  }
+
+  if (flags.allowedTools.length > 0) {
+    const safe = flags.allowedTools.filter(validateToolName);
+    if (safe.length > 0) parts.push('--allowedTools', safe.join(','));
+  }
+  if (flags.disallowedTools.length > 0) {
+    const safe = flags.disallowedTools.filter(validateToolName);
+    if (safe.length > 0) parts.push('--disallowedTools', safe.join(','));
+  }
+
+  if (flags.appendSystemPrompt) {
+    const sanitized = flags.appendSystemPrompt.replace(/\n/g, '\\n');
+    parts.push('--append-system-prompt', `'${shellQuote(sanitized)}'`);
+  }
+
+  return parts.join(' ');
+}
+
+/**
+ * Build env var prefix string for dispatch commands.
+ * Keys are validated against POSIX naming rules.
+ * Returns empty string if no vars configured.
+ */
+export function buildEnvVarPrefix(envVars: Record<string, string>): string {
+  const entries = Object.entries(envVars).filter(([k]) => validateEnvKey(k));
+  if (entries.length === 0) return '';
+  return entries
+    .map(([k, v]) => `${k}='${v.replace(/'/g, "'\\''")}'`)
+    .join(' ') + ' ';
+}

package/server/utils/json-fields.test.ts

@@ -0,0 +1,83 @@
+import { describe, it, expect } from 'vitest';
+import { parseJsonFields } from './json-fields.js';
+
+describe('parseJsonFields', () => {
+  it('parses stringified JSON arrays in known fields', () => {
+    const row = { tags: '["a","b"]', blocked_by: '[1,2]', title: 'scope-1' };
+    const result = parseJsonFields(row);
+    expect(result.tags).toEqual(['a', 'b']);
+    expect(result.blocked_by).toEqual([1, 2]);
+    expect(result.title).toBe('scope-1');
+  });
+
+  it('parses stringified JSON objects in data field', () => {
+    const row = { data: '{"key":"val","nested":{"a":1}}' };
+    const result = parseJsonFields(row);
+    expect(result.data).toEqual({ key: 'val', nested: { a: 1 } });
+  });
+
+  it('handles all 7 known JSON fields', () => {
+    const row = {
+      tags: '[]', blocked_by: '[]', blocks: '[]',
+      data: '{}', discoveries: '[]', next_steps: '[]', details: '{}',
+    };
+    const result = parseJsonFields(row);
+    expect(result.tags).toEqual([]);
+    expect(result.blocked_by).toEqual([]);
+    expect(result.blocks).toEqual([]);
+    expect(result.data).toEqual({});
+    expect(result.discoveries).toEqual([]);
+    expect(result.next_steps).toEqual([]);
+    expect(result.details).toEqual({});
+  });
+
+  it('passes through already-parsed objects untouched', () => {
+    const tags = ['a', 'b'];
+    const row = { tags, data: { foo: 1 } };
+    const result = parseJsonFields(row);
+    expect(result.tags).toBe(tags); // same reference — not re-parsed
+    expect(result.data).toEqual({ foo: 1 });
+  });
+
+  it('keeps malformed JSON strings as-is without throwing', () => {
+    const row = { tags: '{broken json', data: 'not json at all', blocks: '["valid"]' };
+    const result = parseJsonFields(row);
+    expect(result.tags).toBe('{broken json');
+    expect(result.data).toBe('not json at all');
+    expect(result.blocks).toEqual(['valid']);
+  });
+
+  it('returns row unchanged when no JSON fields are present', () => {
+    const row = { id: 1, title: 'hello', status: 'active' };
+    const result = parseJsonFields(row);
+    expect(result).toEqual(row);
+  });
+
+  it('does not mutate the original row', () => {
+    const row = { tags: '["x"]', title: 'scope' };
+    const result = parseJsonFields(row);
+    expect(row.tags).toBe('["x"]'); // original unchanged
+    expect(result.tags).toEqual(['x']); // copy was parsed
+    expect(result).not.toBe(row);
+  });
+
+  it('handles null and undefined field values', () => {
+    const row = { tags: null, data: undefined, blocks: '["a"]' };
+    const result = parseJsonFields(row);
+    expect(result.tags).toBeNull();
+    expect(result.data).toBeUndefined();
+    expect(result.blocks).toEqual(['a']);
+  });
+
+  it('handles empty row', () => {
+    const result = parseJsonFields({});
+    expect(result).toEqual({});
+  });
+
+  it('ignores non-JSON-field strings', () => {
+    const row = { title: '["not a json field"]', tags: '["real"]' };
+    const result = parseJsonFields(row);
+    expect(result.title).toBe('["not a json field"]'); // title is not in JSON_FIELDS
+    expect(result.tags).toEqual(['real']);
+  });
+});

package/server/utils/json-fields.ts

@@ -0,0 +1,14 @@
+const JSON_FIELDS = ['tags', 'blocked_by', 'blocks', 'data', 'discoveries', 'next_steps', 'details'];
+
+export type Row = Record<string, unknown>;
+
+/** Parse stringified JSON fields in a database row back to objects. */
+export function parseJsonFields(row: Row): Row {
+  const parsed = { ...row };
+  for (const field of JSON_FIELDS) {
+    if (typeof parsed[field] === 'string') {
+      try { parsed[field] = JSON.parse(parsed[field] as string); } catch { /* keep string */ }
+    }
+  }
+  return parsed;
+}

package/server/utils/logger.ts

@@ -33,8 +33,14 @@ const useColor = process.stdout.isTTY && !process.env.NO_COLOR;
 const c = {
   reset: useColor ? '\x1b[0m' : '',
   dim: useColor ? '\x1b[2m' : '',
-  gray: useColor ? '\x1b[90m' : '',
+  green: useColor ? '\x1b[32m' : '',
+  blue: useColor ? '\x1b[34m' : '',
+  magenta: useColor ? '\x1b[35m' : '',
   cyan: useColor ? '\x1b[36m' : '',
+  white: useColor ? '\x1b[37m' : '',
+  gray: useColor ? '\x1b[90m' : '',
+  brightMagenta: useColor ? '\x1b[95m' : '',
+  brightCyan: useColor ? '\x1b[96m' : '',
   yellow: useColor ? '\x1b[33m' : '',
   red: useColor ? '\x1b[31m' : '',
 };
@@ -53,6 +59,34 @@ const LEVEL_LABEL: Record<LogLevel, string> = {
   error: 'ERROR',
 };
 
+// ─── Component Colors ───────────────────────────────────────
+
+const COMPONENT_COLOR: Record<string, string> = {
+  // Scope (green)
+  'scope': c.green, 'scope-watcher': c.green,
+  // Dispatch (magenta)
+  'dispatch': c.magenta, 'dispatch-utils': c.magenta, 'batch': c.magenta,
+  // Git (blue)
+  'git': c.blue, 'worktree': c.blue,
+  // Workflow (cyan)
+  'workflow': c.cyan, 'sprint': c.cyan,
+  // Sync / Config (yellow)
+  'sync': c.yellow, 'config': c.yellow, 'manifest': c.yellow, 'global-config': c.yellow,
+  // Events (white)
+  'event': c.white, 'event-watcher': c.white, 'global-watcher': c.white,
+  // Infrastructure (white)
+  'server': c.white, 'central': c.white, 'database': c.white,
+  'project-context': c.white, 'project-manager': c.white, 'launch': c.white,
+  // Terminal (bright magenta)
+  'terminal': c.brightMagenta,
+  // Services (bright cyan)
+  'gate': c.brightCyan, 'deploy': c.brightCyan, 'telemetry': c.brightCyan, 'version': c.brightCyan,
+};
+
+function componentColor(name: string): string {
+  return COMPONENT_COLOR[name] ?? c.dim;
+}
+
 // ─── Formatting ─────────────────────────────────────────────
 
 function timestamp(): string {
@@ -87,10 +121,13 @@ export interface Logger {
 function write(level: LogLevel, component: string, msg: string, data?: Record<string, unknown>): void {
   if (LEVEL_VALUE[level] < LEVEL_VALUE[currentLevel]) return;
 
-  const color = LEVEL_COLOR[level];
+  const lvl = LEVEL_COLOR[level];
   const label = LEVEL_LABEL[level];
   const kv = formatData(data);
-  const line = `${c.dim}${timestamp()}${c.reset} ${color}${label}${c.reset} ${c.dim}[${component}]${c.reset} ${msg}${kv}\n`;
+  const cc = componentColor(component);
+  // Message uses level color for warn/error (urgency), component color otherwise
+  const mc = (level === 'warn' || level === 'error') ? lvl : cc;
+  const line = `${c.dim}${timestamp()}${c.reset} ${lvl}${label}${c.reset} ${cc}[${component}]${c.reset} ${mc}${msg}${c.reset}${c.dim}${kv}${c.reset}\n`;
 
   if (level === 'warn' || level === 'error') {
     process.stderr.write(line);

package/server/utils/package-info.ts

@@ -0,0 +1,32 @@
+import path from 'path';
+import fs from 'fs';
+import { fileURLToPath } from 'url';
+
+const __selfDir = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * Resolve the root directory of the orbital-command package itself.
+ * Walks up from the current file until it finds package.json.
+ */
+export function getOrbitalRoot(): string {
+  let dir = __selfDir;
+  for (let i = 0; i < 6; i++) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) {
+      return dir;
+    }
+    dir = path.dirname(dir);
+  }
+  // Fallback: assume dev layout (server/utils/ → 2 levels up)
+  return path.resolve(__selfDir, '../..');
+}
+
+/** Read package version from package.json in the given root, or the orbital root. */
+export function getPackageVersion(rootDir?: string): string {
+  try {
+    const dir = rootDir ?? getOrbitalRoot();
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
+    return pkg.version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}

package/server/utils/route-helpers.test.ts

@@ -0,0 +1,144 @@
+import { describe, it, expect } from 'vitest';
+import express from 'express';
+import request from 'supertest';
+import { errMsg, isValidRelativePath, inferErrorStatus, catchRoute } from './route-helpers.js';
+
+// ─── errMsg ─────────────────────────────────────────────────
+
+describe('errMsg', () => {
+  it('extracts message from Error instances', () => {
+    expect(errMsg(new Error('something broke'))).toBe('something broke');
+  });
+
+  it('converts non-Error values to strings', () => {
+    expect(errMsg('raw string')).toBe('raw string');
+    expect(errMsg(42)).toBe('42');
+    expect(errMsg(null)).toBe('null');
+    expect(errMsg(undefined)).toBe('undefined');
+  });
+});
+
+// ─── isValidRelativePath ────────────────────────────────────
+
+describe('isValidRelativePath', () => {
+  it('accepts normal relative paths', () => {
+    expect(isValidRelativePath('hooks/init.sh')).toBe(true);
+    expect(isValidRelativePath('agents/attacker/AGENT.md')).toBe(true);
+    expect(isValidRelativePath('file.txt')).toBe(true);
+  });
+
+  it('rejects directory traversal', () => {
+    expect(isValidRelativePath('../etc/passwd')).toBe(false);
+    expect(isValidRelativePath('hooks/../../secret')).toBe(false);
+  });
+
+  it('rejects absolute paths', () => {
+    expect(isValidRelativePath('/etc/passwd')).toBe(false);
+  });
+
+  it('rejects null bytes', () => {
+    expect(isValidRelativePath('file\0.txt')).toBe(false);
+  });
+});
+
+// ─── inferErrorStatus ───────────────────────────────────────
+
+describe('inferErrorStatus', () => {
+  it('returns 403 for traversal errors', () => {
+    expect(inferErrorStatus('Path traversal detected')).toBe(403);
+    expect(inferErrorStatus('directory traversal not allowed')).toBe(403);
+  });
+
+  it('returns 404 for not-found errors', () => {
+    expect(inferErrorStatus('File not found')).toBe(404);
+    expect(inferErrorStatus('ENOENT: no such file')).toBe(404);
+  });
+
+  it('returns 409 for already-exists errors', () => {
+    expect(inferErrorStatus('File already exists at path')).toBe(409);
+  });
+
+  it('returns 400 for directory errors', () => {
+    expect(inferErrorStatus('Cannot delete directory')).toBe(400);
+  });
+
+  it('returns 500 for unrecognized errors', () => {
+    expect(inferErrorStatus('something unexpected')).toBe(500);
+    expect(inferErrorStatus('')).toBe(500);
+  });
+
+  it('matches the first keyword when multiple are present', () => {
+    // "traversal" comes first in the chain, should win
+    expect(inferErrorStatus('traversal not found')).toBe(403);
+  });
+});
+
+// ─── catchRoute ─────────────────────────────────────────────
+
+describe('catchRoute', () => {
+  function createApp(handler: express.RequestHandler) {
+    const app = express();
+    app.get('/test', handler);
+    return app;
+  }
+
+  it('returns normal response when handler succeeds', async () => {
+    const app = createApp(catchRoute((_req, res) => {
+      res.json({ ok: true });
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(200);
+    expect(res.body).toEqual({ ok: true });
+  });
+
+  it('catches sync throws and returns 500', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('sync failure');
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'sync failure' });
+  });
+
+  it('catches async throws and returns 500', async () => {
+    const app = createApp(catchRoute(async () => {
+      throw new Error('async failure');
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'async failure' });
+  });
+
+  it('uses custom statusFn for error status codes', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('File not found at path');
+    }, inferErrorStatus));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(404);
+    expect(res.body).toEqual({ success: false, error: 'File not found at path' });
+  });
+
+  it('uses custom statusFn for traversal errors', async () => {
+    const app = createApp(catchRoute(() => {
+      throw new Error('Path traversal detected');
+    }, inferErrorStatus));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(403);
+  });
+
+  it('handles non-Error thrown values', async () => {
+    const app = createApp(catchRoute(() => {
+      // eslint-disable-next-line no-throw-literal
+      throw 'raw string error';
+    }));
+
+    const res = await request(app).get('/test');
+    expect(res.status).toBe(500);
+    expect(res.body).toEqual({ success: false, error: 'raw string error' });
+  });
+});