ninja-terminals 2.3.1 → 2.3.2

package/mcp-server.js

@@ -23,14 +23,25 @@ const os = require('os');
 
 // ── Lib imports ─────────────────────────────────────────────
 const { LineBuffer, RawBuffer } = require('./lib/ring-buffer');
-const { stripAnsi, detectStatus, extractContextPct, extractStructuredEvents } = require('./lib/status-detect');
+const { stripAnsi, detectStatus, extractContextPct, extractStructuredEvents, parseTaskStatus } = require('./lib/status-detect');
 const { SSEManager } = require('./lib/sse');
 const { writeWorkerSettings } = require('./lib/settings-gen');
 const { getPreDispatchContext, formatContextForInjection } = require('./lib/pre-dispatch');
 const { runPostSession } = require('./lib/post-session');
+const {
+  findAvailablePort,
+  writeRuntimeSession,
+  updateRuntimeSession,
+  readRuntimeSession,
+  healthCheckSession,
+  clearRuntimeSession,
+  readAuthToken,
+  writeAuthToken,
+} = require('./lib/runtime-session');
 
 // ── Config ──────────────────────────────────────────────────
-const HTTP_PORT = parseInt(process.env.HTTP_PORT || '3300', 10);
+const PREFERRED_HTTP_PORT = parseInt(process.env.HTTP_PORT || '3300', 10);
+let HTTP_PORT = PREFERRED_HTTP_PORT;
 const CLAUDE_CMD = process.env.CLAUDE_CMD || 'claude --dangerously-skip-permissions';
 const SHELL = process.env.SHELL || '/bin/zsh';
 const PROJECT_DIR = __dirname;
@@ -38,6 +49,20 @@ const INJECT_GUIDANCE = process.env.INJECT_GUIDANCE !== 'false';
 
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
+// Delay between text and Enter for Claude Code to recognize as submission (not paste buffer)
+const SUBMIT_DELAY_MS = 180;
+
+/**
+ * Submit text to a terminal with delayed Enter.
+ * Claude Code treats text+Enter in the same PTY write as pasted multiline input and buffers it.
+ */
+async function submitToTerminal(terminal, text) {
+  const cleanText = text.replace(/[\r\n]+$/, '');
+  terminal.pty.write(cleanText);
+  await sleep(SUBMIT_DELAY_MS);
+  terminal.pty.write('\r');
+}
+
 // ── Global State ────────────────────────────────────────────
 let nextId = 1;
 const terminals = new Map();
@@ -76,6 +101,9 @@ function getTerminalInfo(t) {
     id: t.id,
     label: t.label,
     status: t.status,
+    taskStatus: t.taskStatus.state,
+    taskStatusMessage: t.taskStatus.message,
+    taskStatusUpdatedAt: t.taskStatus.updatedAt,
     elapsed: getElapsed(t),
     contextPct: extractContextPct(recentLines),
     taskName: t.taskName,
@@ -92,8 +120,13 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
   const cols = 120;
   const rows = 30;
 
-  const workDir = cwd || PROJECT_DIR;
-  const settingsDir = cwd || PROJECT_DIR;
+  // Validate cwd to prevent broken paths like "\" from corrupting terminal startup
+  let workDir = cwd || PROJECT_DIR;
+  if (!workDir || workDir.length < 2 || !path.isAbsolute(workDir)) {
+    console.warn(`[spawn] Invalid cwd "${workDir}", falling back to PROJECT_DIR`);
+    workDir = PROJECT_DIR;
+  }
+  const settingsDir = workDir;
 
   // Write worker settings
   try {
@@ -148,6 +181,14 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
     progress: null,
     scope: Array.isArray(scope) ? scope : (scope ? [scope] : []),
     cwd: workDir,
+    // Semantic task status (separate from process status)
+    taskStatus: {
+      state: 'pending',
+      marker: null,
+      message: null,
+      updatedAt: new Date().toISOString(),
+      source: 'init',
+    },
   };
 
   // PTY data handler
@@ -169,6 +210,30 @@ function spawnTerminal(label, scope = [], cwd = null, tier = 'pro') {
       sse.broadcast(evt.type, evt);
     }
 
+    // Parse task status from recent buffered lines (handles split chunks)
+    const recentLines = terminal.lineBuffer.last(20);
+    const taskStatusResult = parseTaskStatus(recentLines);
+    if (taskStatusResult) {
+      const prevState = terminal.taskStatus.state;
+      if (prevState !== taskStatusResult.state) {
+        terminal.taskStatus = {
+          state: taskStatusResult.state,
+          marker: taskStatusResult.marker,
+          message: taskStatusResult.message,
+          updatedAt: new Date().toISOString(),
+          source: 'output-parser',
+        };
+        sse.broadcast('task_status_change', {
+          terminal: terminal.label,
+          id: terminal.id,
+          processStatus: terminal.status,
+          taskStatus: terminal.taskStatus,
+          ts: terminal.taskStatus.updatedAt,
+        });
+        console.error(`[task-status] T${terminal.id} (${terminal.label}): ${prevState} -> ${taskStatusResult.state}`);
+      }
+    }
+
     // Broadcast to WebSocket clients
     for (const ws of terminal.clients) {
       if (ws.readyState === 1) ws.send(data);
@@ -288,6 +353,55 @@ app.get('/api/events', (req, res) => {
   req.on('close', () => sse.removeClient(res));
 });
 
+app.get('/api/auth/bootstrap', (req, res) => {
+  const token = readAuthToken();
+  if (!token) {
+    res.status(404).json({ error: 'No saved token' });
+    return;
+  }
+  res.set('Cache-Control', 'no-store');
+  res.json({ token });
+});
+
+app.post('/api/session', (req, res) => {
+  const authHeader = req.headers.authorization || '';
+  const token = authHeader.startsWith('Bearer ') ? authHeader.slice(7) : req.body?.token || readAuthToken();
+  if (token) {
+    writeAuthToken(token);
+    updateRuntimeSession({
+      authToken: token,
+      tier: activeSession.tier,
+      terminalsMax: activeSession.terminalsMax,
+      features: activeSession.features,
+      activeSessionCreatedAt: new Date(activeSession.createdAt).toISOString(),
+    });
+  }
+
+  const existingTerminals = [...terminals.values()].map(t => ({
+    id: t.id,
+    label: t.label,
+    status: t.status,
+    cwd: t.cwd,
+  }));
+
+  res.json({
+    tier: activeSession.tier,
+    terminalsMax: activeSession.terminalsMax,
+    features: activeSession.features,
+    terminals: existingTerminals,
+  });
+});
+
+app.get('/api/session', (_req, res) => {
+  res.json({
+    active: true,
+    tier: activeSession.tier,
+    terminalsMax: activeSession.terminalsMax,
+    features: activeSession.features,
+    terminals: [...terminals.values()].map(t => getTerminalInfo(t)),
+  });
+});
+
 app.get('/api/terminals', (_req, res) => {
   const list = [];
   for (const [, t] of terminals) {
@@ -296,6 +410,86 @@ app.get('/api/terminals', (_req, res) => {
   res.json(list);
 });
 
+app.get('/api/terminals/task-status', (_req, res) => {
+  res.json([...terminals.values()].map(t => ({
+    id: t.id,
+    label: t.label,
+    processStatus: t.status,
+    taskStatus: t.taskStatus.state,
+    marker: t.taskStatus.marker,
+    message: t.taskStatus.message,
+    updatedAt: t.taskStatus.updatedAt,
+  })));
+});
+
+app.get('/api/terminals/:id/status', (req, res) => {
+  const terminal = terminals.get(parseInt(req.params.id, 10));
+  if (!terminal) return res.status(404).json({ error: 'Not found' });
+  res.json(getTerminalInfo(terminal));
+});
+
+app.get('/api/terminals/:id/task-status', (req, res) => {
+  const terminal = terminals.get(parseInt(req.params.id, 10));
+  if (!terminal) return res.status(404).json({ error: 'Not found' });
+  res.json({
+    id: terminal.id,
+    label: terminal.label,
+    processStatus: terminal.status,
+    taskStatus: terminal.taskStatus.state,
+    marker: terminal.taskStatus.marker,
+    message: terminal.taskStatus.message,
+    updatedAt: terminal.taskStatus.updatedAt,
+  });
+});
+
+app.get('/api/terminals/:id/output', (req, res) => {
+  const terminal = terminals.get(parseInt(req.params.id, 10));
+  if (!terminal) return res.status(404).json({ error: 'Not found' });
+  const lines = Math.max(1, parseInt(req.query.lines, 10) || 50);
+  res.json({ lines: terminal.lineBuffer.last(lines) });
+});
+
+app.post('/api/terminals/:id/input', async (req, res) => {
+  const terminal = terminals.get(parseInt(req.params.id, 10));
+  if (!terminal) return res.status(404).json({ error: 'Not found' });
+
+  const text = req.body?.text || req.body?.input || '';
+  if (!text) return res.status(400).json({ error: 'text required' });
+
+  const prevTaskState = terminal.taskStatus.state;
+  terminal.taskStatus = {
+    state: 'running',
+    marker: null,
+    message: `Dispatched: ${text.slice(0, 80)}${text.length > 80 ? '...' : ''}`,
+    updatedAt: new Date().toISOString(),
+    source: 'dispatch',
+  };
+  sse.broadcast('task_status_change', {
+    terminal: terminal.label,
+    id: terminal.id,
+    processStatus: terminal.status,
+    taskStatus: terminal.taskStatus,
+    ts: terminal.taskStatus.updatedAt,
+  });
+  console.error(`[task-status] T${terminal.id} (${terminal.label}): ${prevTaskState} -> running (http dispatch)`);
+
+  let finalText = text;
+  let guidanceInjected = false;
+  if (INJECT_GUIDANCE) {
+    try {
+      const ctx = await getPreDispatchContext();
+      const hasGuidance = ctx.toolGuidance.length > 0 || ctx.playbookInsights.length > 0;
+      if (hasGuidance) {
+        finalText = `${formatContextForInjection(ctx)}\n\n${text}`;
+        guidanceInjected = true;
+      }
+    } catch { /* continue without guidance */ }
+  }
+
+  await submitToTerminal(terminal, finalText);
+  res.json({ ok: true, guidanceInjected });
+});
+
 // ── MCP Server Setup ────────────────────────────────────────
 
 const mcpServer = new Server(
@@ -470,6 +664,24 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
           return { content: [{ type: 'text', text: JSON.stringify({ error: 'Terminal not found' }) }], isError: true };
         }
 
+        // Reset task status on new dispatch
+        const prevTaskState = terminal.taskStatus.state;
+        terminal.taskStatus = {
+          state: 'running',
+          marker: null,
+          message: `Dispatched: ${args.text.slice(0, 80)}${args.text.length > 80 ? '...' : ''}`,
+          updatedAt: new Date().toISOString(),
+          source: 'dispatch',
+        };
+        sse.broadcast('task_status_change', {
+          terminal: terminal.label,
+          id: terminal.id,
+          processStatus: terminal.status,
+          taskStatus: terminal.taskStatus,
+          ts: terminal.taskStatus.updatedAt,
+        });
+        console.error(`[task-status] T${terminal.id} (${terminal.label}): ${prevTaskState} -> running (dispatch)`);
+
         let finalText = args.text;
         let guidanceInjected = false;
 
@@ -485,7 +697,8 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
           } catch { /* continue without guidance */ }
         }
 
-        terminal.pty.write(finalText);
+        // Use delayed Enter for proper Claude Code submission
+        await submitToTerminal(terminal, finalText);
         return {
           content: [{ type: 'text', text: JSON.stringify({ ok: true, guidanceInjected }) }],
         };
@@ -613,6 +826,24 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
         terminal.progress = null;
         terminal.taskStartedAt = Date.now();
 
+        // Reset task status on new task assignment
+        const prevTaskState = terminal.taskStatus.state;
+        terminal.taskStatus = {
+          state: 'running',
+          marker: null,
+          message: `Task: ${args.name}${args.description ? ` — ${args.description.slice(0, 60)}` : ''}`,
+          updatedAt: new Date().toISOString(),
+          source: 'task-assign',
+        };
+        sse.broadcast('task_status_change', {
+          terminal: terminal.label,
+          id: terminal.id,
+          processStatus: terminal.status,
+          taskStatus: terminal.taskStatus,
+          ts: terminal.taskStatus.updatedAt,
+        });
+        console.error(`[task-status] T${terminal.id} (${terminal.label}): ${prevTaskState} -> running (task-assign)`);
+
         if (args.scope) {
           terminal.scope = Array.isArray(args.scope) ? args.scope : [args.scope];
         }
@@ -626,9 +857,9 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
           ts: new Date().toISOString(),
         });
 
-        // Send task description as input
+        // Send task description as input with delayed Enter
         if (args.description) {
-          terminal.pty.write(`${args.description}\r`);
+          await submitToTerminal(terminal, args.description);
         }
 
         return {
@@ -694,36 +925,38 @@ mcpServer.setRequestHandler(CallToolRequestSchema, async (request) => {
 
 // ── Start Servers ───────────────────────────────────────────
 
-// Check if port is in use
-function isPortInUse(port) {
-  return new Promise((resolve) => {
-    const net = require('net');
-    const server = net.createServer();
-    server.once('error', () => resolve(true));
-    server.once('listening', () => {
-      server.close();
-      resolve(false);
-    });
-    server.listen(port, '127.0.0.1');
-  });
-}
-
 // Proxy mode flag - when true, MCP tools should call existing server via HTTP
 let proxyMode = false;
+let ownsRuntimeSession = false;
 
 async function main() {
-  // Check if server.js is already running on port 3300
-  const portInUse = await isPortInUse(HTTP_PORT);
+  const runtimeSession = readRuntimeSession();
+  const runtimeHealth = await healthCheckSession(runtimeSession);
 
-  if (portInUse) {
+  if (runtimeHealth.ok) {
     // Proxy mode: server.js is already running, just run MCP on stdio
     proxyMode = true;
+    HTTP_PORT = runtimeSession.port;
     console.error(`Ninja Terminals server already running on port ${HTTP_PORT}`);
     console.error('MCP server starting in proxy mode (will use existing server)');
   } else {
+    HTTP_PORT = await findAvailablePort(PREFERRED_HTTP_PORT);
+    if (HTTP_PORT !== PREFERRED_HTTP_PORT) {
+      console.error(`Ninja Terminals preferred HTTP port ${PREFERRED_HTTP_PORT} unavailable; using ${HTTP_PORT}`);
+    }
+
     // Standalone mode: start our own HTTP server
     httpServer.listen(HTTP_PORT, () => {
-      console.error(`Ninja Terminals HTTP server running on http://localhost:${HTTP_PORT}`);
+      const url = `http://localhost:${HTTP_PORT}`;
+      writeRuntimeSession({
+        port: HTTP_PORT,
+        url,
+        cwd: PROJECT_DIR,
+        terminals: parseInt(process.env.NINJA_TERMINAL_COUNT || '2', 10),
+        command: 'ninja-terminals-mcp',
+      });
+      ownsRuntimeSession = true;
+      console.error(`Ninja Terminals HTTP server running on ${url}`);
 
       // Auto-spawn terminals based on tier (NINJA_TERMINAL_COUNT env var)
       // Free = 2, Paid = 4
@@ -750,3 +983,12 @@ main().catch((err) => {
   console.error('Fatal error:', err);
   process.exit(1);
 });
+
+process.on('exit', () => {
+  if (!ownsRuntimeSession) return;
+  try {
+    clearRuntimeSession();
+  } catch {
+    // ignore shutdown cleanup failures
+  }
+});

package/ninja-claude-visual.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+'use strict';
+
+process.env.NINJA_VISUAL_COMMAND = 'ninja-claude-visual';
+
+const { runCli } = require('./ninja-codex-visual');
+
+runCli().then((code) => {
+  process.exit(code);
+}).catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/ninja-codex-visual.js

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const {
+  SESSION_DIR,
+  VALID_VISUAL_STAGES,
+  appendVisualEntry,
+  readRuntimeSession,
+} = require('./lib/runtime-session');
+
+const USAGE = `
+Usage:
+  ninja-codex-visual --record <stage> [--note "..."] [--terminal <id>] [--expect-task <state>] [--screenshot] [--json]
+
+Uses Playwright to inspect the local Ninja Terminal UI before recording visual evidence.
+
+Examples:
+  ninja-codex-visual --record pre-dispatch --note "T1-T4 visible"
+  ninja-codex-visual --record post-output --terminal 1 --expect-task done --screenshot
+
+Valid stages: ${VALID_VISUAL_STAGES.join(', ')}
+Expected task states: pending, running, done, blocked, error, unknown
+`;
+
+const VALID_TASK_EXPECTATIONS = ['pending', 'running', 'done', 'blocked', 'error', 'unknown'];
+
+function commandName() {
+  if (process.env.NINJA_VISUAL_COMMAND) return process.env.NINJA_VISUAL_COMMAND;
+  return path.basename(process.argv[1] || 'ninja-codex-visual', '.js');
+}
+
+function parseArgs(argv) {
+  const opts = {
+    command: null,
+    stage: null,
+    note: null,
+    terminalId: null,
+    expectTask: null,
+    screenshot: false,
+    json: false,
+    url: null,
+    timeoutMs: 10000,
+    headful: false,
+  };
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') {
+      opts.command = 'help';
+    } else if (arg === '--record') {
+      opts.command = 'record';
+      opts.stage = argv[++i];
+      if (!opts.stage) throw new Error('--record requires a stage');
+    } else if (arg === '--note') {
+      opts.note = argv[++i];
+      if (!opts.note) throw new Error('--note requires text');
+    } else if (arg === '--terminal') {
+      opts.terminalId = argv[++i];
+      if (!opts.terminalId) throw new Error('--terminal requires an id');
+    } else if (arg === '--expect-task') {
+      opts.expectTask = argv[++i];
+      if (!opts.expectTask) throw new Error('--expect-task requires a state');
+    } else if (arg === '--screenshot') {
+      opts.screenshot = true;
+    } else if (arg === '--json') {
+      opts.json = true;
+    } else if (arg === '--url') {
+      opts.url = argv[++i];
+      if (!opts.url) throw new Error('--url requires a URL');
+    } else if (arg === '--timeout') {
+      opts.timeoutMs = Number.parseInt(argv[++i], 10);
+      if (!Number.isInteger(opts.timeoutMs) || opts.timeoutMs < 1000) {
+        throw new Error('--timeout must be an integer >= 1000');
+      }
+    } else if (arg === '--headful') {
+      opts.headful = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return opts;
+}
+
+function validateRecordOptions(opts) {
+  if (opts.command !== 'record') throw new Error('Only --record is supported');
+  if (!VALID_VISUAL_STAGES.includes(opts.stage)) {
+    throw new Error(`Invalid stage "${opts.stage}". Valid stages: ${VALID_VISUAL_STAGES.join(', ')}`);
+  }
+  if (opts.expectTask && !VALID_TASK_EXPECTATIONS.includes(opts.expectTask)) {
+    throw new Error(`Invalid --expect-task "${opts.expectTask}". Valid states: ${VALID_TASK_EXPECTATIONS.join(', ')}`);
+  }
+}
+
+function resolveUrl(opts) {
+  if (opts.url) return opts.url;
+  const session = readRuntimeSession();
+  if (!session || !session.url) {
+    throw new Error('No Ninja runtime URL found. Run node ninja-ensure.js first.');
+  }
+  return session.url;
+}
+
+function screenshotPath() {
+  const dir = path.join(SESSION_DIR, 'screenshots');
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(dir, `codex-visual-${stamp}.png`);
+}
+
+function loadPlaywright() {
+  try {
+    return require('playwright');
+  } catch (err) {
+    throw new Error('Playwright is not available. Install or expose playwright before using ninja-codex-visual.');
+  }
+}
+
+async function inspectNinjaUi(opts) {
+  const { chromium } = loadPlaywright();
+  const url = resolveUrl(opts);
+  const browser = await chromium.launch({ headless: !opts.headful });
+
+  try {
+    const page = await browser.newPage({ viewport: { width: 1280, height: 900 } });
+    await page.goto(url, { waitUntil: 'domcontentloaded', timeout: opts.timeoutMs });
+    await page.reload({ waitUntil: 'domcontentloaded', timeout: opts.timeoutMs });
+    await page.waitForSelector('.terminal-pane', { timeout: opts.timeoutMs });
+    await page.waitForTimeout(250);
+
+    const observation = await page.evaluate(() => {
+      const logo = document.querySelector('.logo-text, .logo')?.textContent?.trim() || '';
+      const panes = [...document.querySelectorAll('.terminal-pane')].map((pane) => {
+        const id = pane.id ? pane.id.replace(/^pane-/, '') : '';
+        const rect = pane.getBoundingClientRect();
+        return {
+          id,
+          label: pane.querySelector('.pane-label')?.textContent?.trim() || '',
+          processStatus: pane.querySelector('.state-text')?.textContent?.trim().toLowerCase() || '',
+          taskStatus: pane.querySelector('.task-text')?.textContent?.trim().toLowerCase() || '',
+          visible: rect.width > 0 && rect.height > 0,
+        };
+      });
+
+      return {
+        title: document.title,
+        logo,
+        terminalCount: panes.length,
+        panes,
+      };
+    });
+
+    if (!/ninja terminals/i.test(observation.logo) && !/ninja/i.test(observation.title || '')) {
+      throw new Error(`Ninja UI not detected at ${url}`);
+    }
+
+    const visiblePanes = observation.panes.filter(p => p.visible);
+    if (visiblePanes.length === 0) {
+      throw new Error('No visible terminal panes found');
+    }
+
+    if (opts.terminalId) {
+      const terminal = observation.panes.find(p => String(p.id) === String(opts.terminalId));
+      if (!terminal) throw new Error(`Terminal ${opts.terminalId} not found in UI`);
+      if (!terminal.visible) throw new Error(`Terminal ${opts.terminalId} exists but is not visible`);
+      if (opts.expectTask && terminal.taskStatus !== opts.expectTask) {
+        throw new Error(`Terminal ${opts.terminalId} task status is ${terminal.taskStatus || 'missing'}, expected ${opts.expectTask}`);
+      }
+    }
+
+    let shotPath = null;
+    if (opts.screenshot) {
+      shotPath = screenshotPath();
+      await page.screenshot({ path: shotPath, fullPage: true });
+    }
+
+    return {
+      url,
+      screenshot: shotPath,
+      observation,
+    };
+  } finally {
+    await browser.close();
+  }
+}
+
+function buildNote(opts, inspection) {
+  if (opts.note) return opts.note.trim();
+  const parts = [
+    `Ninja UI visible at ${inspection.url}`,
+    `${inspection.observation.terminalCount} terminal pane(s) found`,
+  ];
+  if (opts.terminalId) parts.push(`T${opts.terminalId} visible`);
+  if (opts.expectTask) parts.push(`task=${opts.expectTask}`);
+  return parts.join(', ');
+}
+
+async function runCli(argv = process.argv.slice(2)) {
+  const opts = parseArgs(argv);
+  if (opts.command === 'help' || !opts.command) {
+    console.log(USAGE);
+    return opts.command === 'help' ? 0 : 1;
+  }
+
+  validateRecordOptions(opts);
+  const inspection = await inspectNinjaUi(opts);
+  const entry = {
+    stage: opts.stage,
+    note: buildNote(opts, inspection),
+    cwd: process.cwd(),
+    command: commandName(),
+    source: 'playwright',
+    url: inspection.url,
+    observed: {
+      title: inspection.observation.title,
+      logo: inspection.observation.logo,
+      terminalCount: inspection.observation.terminalCount,
+      panes: inspection.observation.panes,
+    },
+  };
+  if (opts.terminalId) entry.terminalId = String(opts.terminalId);
+  if (opts.expectTask) entry.expectTask = opts.expectTask;
+  if (inspection.screenshot) entry.screenshot = inspection.screenshot;
+
+  const record = appendVisualEntry(entry);
+
+  if (opts.json) {
+    console.log(JSON.stringify(record, null, 2));
+  } else {
+    console.log(`${commandName()} verification recorded: [${record.stage}]${record.terminalId ? ` T${record.terminalId}` : ''}`);
+    console.log(`  ${record.note}`);
+    if (record.screenshot) console.log(`  Screenshot: ${record.screenshot}`);
+  }
+
+  return 0;
+}
+
+if (require.main === module) {
+  runCli().then((code) => {
+    process.exit(code);
+  }).catch((err) => {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  });
+}
+
+module.exports = {
+  VALID_TASK_EXPECTATIONS,
+  buildNote,
+  commandName,
+  inspectNinjaUi,
+  parseArgs,
+  runCli,
+  validateRecordOptions,
+};