levante 0.1.4 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "levante",
-  "version": "0.1.4",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "levante": "./dist/cli.js",
@@ -18,25 +18,25 @@
   },
   "files": ["dist/", "agents/", "scripts/", "templates/"],
   "scripts": {
-    "build": "bun build src/cli.ts src/index.ts src/config/schema.ts src/mcp.ts --outdir dist --target node --format esm --splitting",
+    "build": "bun build src/cli.ts src/index.ts src/config/schema.ts src/mcp.ts --outdir dist --target node --format esm --packages=bundle",
     "dev": "bun run src/cli.ts"
   },
-  "dependencies": {
+  "peerDependencies": {
+    "@playwright/test": ">=1.40.0"
+  },
+  "devDependencies": {
     "@inquirer/prompts": "^8.3.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
+    "@qai/cli-auth": "workspace:*",
+    "@types/node": "^24.0.14",
     "commander": "^13.1.0",
     "dotenv": "^17.2.0",
     "glob": "^13.0.6",
     "ora": "^9.3.0",
     "picocolors": "^1.1.1",
+    "typescript": "^5.8.3",
+    "ws": "^8.19.0",
     "yaml": "^2.7.1",
     "zod": "^4.0.5"
-  },
-  "peerDependencies": {
-    "@playwright/test": ">=1.40.0"
-  },
-  "devDependencies": {
-    "@types/node": "^24.0.14",
-    "typescript": "^5.8.3"
   }
 }

package/scripts/auth/setup-auth.mjs

@@ -8,10 +8,9 @@
  *
  * Usage:
  *   node scripts/auth/setup-auth.mjs                          # single resource (default)
- *   node scripts/auth/setup-auth.mjs --multi                  # multi resource
  *   node scripts/auth/setup-auth.mjs --output .auth/custom.json
  *
- * Credentials come from .env (USERNAME/PASSWORD or MULTI_RESOURCE_USERNAME/PASSWORD).
+ * Credentials come from .env (USERNAME/PASSWORD).
  * Storage state is saved to .auth/codegen.json by default.
  */
 
@@ -43,21 +42,15 @@ function loadEnv() {
 loadEnv();
 
 const args = process.argv.slice(2);
-const isMulti = args.includes('--multi');
 const outputIdx = args.indexOf('--output');
 const customOutput = outputIdx !== -1 ? args[outputIdx + 1] : null;
 
-const username = isMulti
-  ? process.env.MULTI_RESOURCE_USERNAME
-  : process.env.SINGLE_RESOURCE_USERNAME;
-const password = isMulti
-  ? process.env.MULTI_RESOURCE_PASSWORD
-  : process.env.SINGLE_RESOURCE_PASSWORD;
+const username = process.env.USERNAME;
+const password = process.env.PASSWORD;
 const baseUrl = process.env.BASE_URL;
 
 if (!username || !password) {
-  const prefix = isMulti ? 'MULTI_RESOURCE' : 'SINGLE_RESOURCE';
-  console.error(`Missing ${prefix}_USERNAME or ${prefix}_PASSWORD in .env`);
+  console.error(`Missing USERNAME or PASSWORD in .env`);
   process.exit(1);
 }
 if (!baseUrl) {

package/scripts/codegen-env.mjs

@@ -15,13 +15,33 @@
  *   E2E_AI_KEY=PROJ-101 node codegen-env.mjs
  */
 
-import { spawn, execSync } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, writeFileSync, unlinkSync, renameSync } from 'node:fs';
-import { dirname, resolve, relative, isAbsolute } from 'node:path';
+import { execSync, spawn } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import pc from 'picocolors';
+import { printError, printHeader, printSuccess, saveErrorLog } from './ui.mjs';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+const warnings = [];
+
+function isoNow() { return new Date().toISOString(); }
+
+// getFixHint is declared here (hoisted function declaration) but only called
+// inside the exit handler, after issueKey is assigned. Safe.
+function getFixHint(msg, key) {
+  if (/USERNAME|PASSWORD/i.test(msg))
+    return 'Set USERNAME and PASSWORD in .env';
+  if (/companion server failed/i.test(msg))
+    return 'Re-run with --no-companion to disable companion UI';
+  if (/trace replay failed/i.test(msg))
+    return `Codegen is saved — run: levante transcribe --key ${key}`;
+  if (/voice processing error/i.test(msg))
+    return 'Codegen is saved — audio may be incomplete';
+  return null;
+}
+
 // Project root: prefer env var, then fall back to parent of scripts dir
 const root = process.env.E2E_AI_PROJECT_ROOT || resolve(__dirname, '..');
 
@@ -87,6 +107,7 @@ const url = baseUrl ? baseUrl.replace(/\/$/, '') : 'about:blank';
 const rawArgs = process.argv.slice(2);
 const voiceEnabled = !rawArgs.includes('--no-voice');
 const traceEnabled = !rawArgs.includes('--no-trace');
+const companionEnabled = voiceEnabled && !rawArgs.includes('--no-companion');
 const positionalArgs = rawArgs.filter((a) => !a.startsWith('--no-'));
 
 const keyInput = positionalArgs[0];
@@ -106,7 +127,6 @@ const workingDirAbs = isAbsolute(workingDirRel) ? workingDirRel : resolve(root,
 const issueDir = resolve(workingDirAbs, issueKey);
 if (!existsSync(issueDir)) {
   mkdirSync(issueDir, { recursive: true });
-  console.error(`Created: ${relative(root, issueDir)}/`);
 }
 
 const now = new Date();
@@ -123,11 +143,6 @@ const defaultOut = resolve(issueDir, `codegen-${timestamp}.ts`);
 const outputPath = customOut ? resolve(root, customOut) : defaultOut;
 const outputRelative = relative(root, outputPath);
 
-console.error(`Issue key: ${issueKey}`);
-console.error(`Recording will be saved to: ${outputRelative}`);
-console.error(`Voice recording: ${voiceEnabled ? 'ENABLED' : 'disabled (--no-voice)'}`);
-console.error(`Trace replay:    ${traceEnabled ? 'ENABLED' : 'disabled (--no-trace)'}`);
-console.error('(When you close the Playwright Inspector, the file is written there.)\n');
 
 // --- Session timing (always track, used for action timestamps) ---
 const sessionStartTime = Date.now();
@@ -200,7 +215,146 @@ if (voiceEnabled) {
   recording = true;
   segmentIndex++;
 
-  console.error(`Audio segments saved to: ${relative(root, recordingsDir)}/`);
+  // printRecordingStatus(true) is called after the header (see below)
+}
+
+// --- Companion server setup ---
+let companionProcess = null;
+let companionPort = null;
+let companionWs = null;
+let companionStdoutHandler = null;
+let companionAlreadySaved = null;
+
+if (companionEnabled) {
+  try {
+    const companionScript = resolve(__dirname, 'companion', 'server.mjs');
+    const companionRecDir = recordingsDir || resolve(issueDir, 'recordings');
+    if (!existsSync(companionRecDir)) mkdirSync(companionRecDir, { recursive: true });
+
+    companionProcess = spawn('node', [companionScript], {
+      stdio: ['pipe', 'pipe', 'inherit'],
+      cwd: root,
+      env: {
+        ...process.env,
+        COMPANION_OUTPUT_DIR: companionRecDir,
+        COMPANION_TIMESTAMP: timestamp,
+        OPENAI_API_KEY: process.env.OPENAI_API_KEY || '',
+      },
+    });
+
+    // Single stdout handler — dispatches all JSON-line messages
+    const onCompanionStdout = [];
+    let stdoutBuffer = '';
+    companionProcess.stdout.on('data', (chunk) => {
+      stdoutBuffer += chunk.toString();
+      let newlineIdx;
+      while ((newlineIdx = stdoutBuffer.indexOf('\n')) !== -1) {
+        const line = stdoutBuffer.slice(0, newlineIdx).trim();
+        stdoutBuffer = stdoutBuffer.slice(newlineIdx + 1);
+        if (line) {
+          try {
+            const msg = JSON.parse(line);
+            for (const handler of onCompanionStdout) handler(msg);
+          } catch {
+            process.stderr.write(`[companion] ${line}\n`);
+          }
+        }
+      }
+    });
+
+    // Wait for server-started message
+    companionPort = await new Promise((resolvePort, rejectPort) => {
+      const timeout = setTimeout(() => rejectPort(new Error('Companion server startup timeout')), 5000);
+      const handler = (msg) => {
+        if (msg.type === 'server-started') {
+          clearTimeout(timeout);
+          const idx = onCompanionStdout.indexOf(handler);
+          if (idx !== -1) onCompanionStdout.splice(idx, 1);
+          resolvePort(msg.port);
+        } else if (msg.type === 'server-error') {
+          clearTimeout(timeout);
+          rejectPort(new Error(msg.error));
+        }
+      };
+      onCompanionStdout.push(handler);
+      companionProcess.on('error', (err) => { clearTimeout(timeout); rejectPort(err); });
+      companionProcess.on('exit', (code) => { if (code) { clearTimeout(timeout); rejectPort(new Error(`Companion exited with code ${code}`)); } });
+    });
+
+    companionStdoutHandler = onCompanionStdout;
+
+    // Track whether companion already saved (via Save & Close before codegen closed)
+    const saveExitTranscriptHandler = (msg) => {
+      if (msg.type === 'transcript:saved') {
+        companionAlreadySaved = msg.path;
+      }
+    };
+    onCompanionStdout.push(saveExitTranscriptHandler);
+
+    const saveExitHandler = (msg) => {
+      if (msg.type === 'save-and-exit') {
+        child.kill('SIGTERM');
+      }
+    };
+    onCompanionStdout.push(saveExitHandler);
+
+    // Connect parent to companion WebSocket for hotkey relay
+    const { WebSocket: WsClient } = await import('ws');
+    companionWs = new WsClient(`ws://localhost:${companionPort}`);
+    await new Promise((r) => {
+      companionWs.on('open', r);
+      companionWs.on('error', r);
+    });
+
+    companionWs.on('close', () => {
+      companionWs = null;
+    });
+
+    // Listen for companion messages (e.g., user clicked Save & Close)
+    companionWs.on('message', (raw) => {
+      try {
+        const msg = JSON.parse(raw.toString());
+        if (msg.type === 'save-and-exit') {
+          // User clicked Save & Close in companion — kill codegen to trigger shutdown
+          child.kill('SIGTERM');
+        }
+      } catch {}
+    });
+  } catch (err) {
+    if (err.message.includes('already in use')) {
+      printError('Companion port already in use', [
+        { label: 'Fix', value: 'Stop the other session first, then try again' },
+      ]);
+      process.exit(1);
+    }
+    warnings.push(`[WARN] ${isoNow()} Companion server failed to start: ${err.message}`);
+    warnings.push(`[WARN] ${isoNow()} Continuing without companion UI (voice recording still active)`);
+    companionProcess = null;
+    companionPort = null;
+  }
+}
+
+// --- Print session header (all pre-flight info is now here) ---
+{
+  const flags = [
+    voiceEnabled ? pc.green('Voice ✓') : pc.dim('Voice ✗'),
+    traceEnabled ? pc.green('Trace ✓') : pc.dim('Trace ✗'),
+    (companionEnabled && companionPort) ? pc.green('Companion ✓') : pc.dim('Companion ✗'),
+  ].join('  ');
+
+  const headerItems = [
+    { label: 'Output', value: outputRelative },
+    { label: 'Status', value: flags },
+  ];
+  if (companionPort) {
+    headerItems.push({ label: 'Companion', value: `http://localhost:${companionPort}` });
+  }
+
+  printHeader('levante record', issueKey, headerItems);
+}
+
+// Print recording status line (was previously printed during voice setup)
+if (voiceEnabled && recording) {
   printRecordingStatus(true);
 }
 
@@ -212,15 +366,15 @@ if (!existsSync(authDir)) {
 }
 
 if (!existsSync(storageStatePath)) {
-  console.error('Authenticating to cache storage state...');
   try {
     execSync(`node "${resolve(__dirname, 'auth', 'setup-auth.mjs')}"`, {
       cwd: root,
-      stdio: 'inherit',
+      stdio: 'pipe',
       env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
     });
-  } catch {
-    console.error('Auth setup failed \u2014 codegen will start without cached auth.');
+  } catch (authErr) {
+    const authMsg = (authErr.stderr?.toString().trim() || authErr.message).split('\n')[0];
+    warnings.push(`[WARN] ${isoNow()} Auth setup failed: ${authMsg}`);
   }
 }
 
@@ -233,7 +387,6 @@ if (traceEnabled && harPath) {
 if (existsSync(storageStatePath)) {
   codegenArgs.push('--load-storage', storageStatePath);
   codegenArgs.push('--save-storage', storageStatePath);
-  console.error('Using cached auth \u2014 codegen will start already logged in.');
 }
 codegenArgs.push(url);
 
@@ -246,6 +399,12 @@ const child = spawn('npx', codegenArgs, {
 // Start polling the output file for new actions to capture timestamps
 startActionPolling();
 
+// --- Open companion window ---
+if (companionPort) {
+  const { openUrl } = await import(resolve(__dirname, 'companion', 'open-url.mjs'));
+  openUrl(`http://localhost:${companionPort}/companion`);
+}
+
 // --- Keyboard listener for pause/resume ---
 if (voiceEnabled && process.stdin.isTTY) {
   process.stdin.setRawMode(true);
@@ -266,6 +425,9 @@ if (voiceEnabled && process.stdin.isTTY) {
         currentRecProcess = null;
         recording = false;
         printRecordingStatus(false);
+        if (companionWs && companionWs.readyState === 1) {
+          companionWs.send(JSON.stringify({ type: 'control:pause' }));
+        }
       } else {
         const segPath = resolve(recordingsDir, `seg-${String(segmentIndex).padStart(3, '0')}.wav`);
         segmentPaths.push(segPath);
@@ -274,6 +436,9 @@ if (voiceEnabled && process.stdin.isTTY) {
         recording = true;
         segmentIndex++;
         printRecordingStatus(true);
+        if (companionWs && companionWs.readyState === 1) {
+          companionWs.send(JSON.stringify({ type: 'control:resume' }));
+        }
       }
     }
   });
@@ -287,90 +452,207 @@ function cleanupTerminal() {
   }
 }
 
+function killCompanion() {
+  if (companionProcess) {
+    try { if (companionWs) companionWs.close(); } catch {}
+    try { companionProcess.kill('SIGTERM'); } catch {}
+    try { companionProcess.kill('SIGKILL'); } catch {}
+    companionProcess = null;
+  }
+}
+
+// Ensure companion is killed on any exit path
+process.on('exit', killCompanion);
+process.on('SIGINT', () => { killCompanion(); process.exit(130); });
+process.on('SIGTERM', () => { killCompanion(); process.exit(143); });
+process.on('uncaughtException', (err) => {
+  printError(err.message || String(err), []);
+  killCompanion();
+  process.exit(1);
+});
+
 child.on('exit', async (code) => {
   cleanupTerminal();
   if (pollInterval) clearInterval(pollInterval);
 
-  if (code === 0) {
-    console.error(`\nSaved: ${outputRelative}`);
-  }
+  try {
+    // --- Companion shutdown ---
+    let liveTranscriptPath = null;
+    if (companionProcess) {
+      try {
+        if (companionAlreadySaved) {
+          // User already clicked Save & Close — transcript was saved before codegen closed
+          liveTranscriptPath = companionAlreadySaved;
+          if (companionWs) try { companionWs.close(); } catch {}
+          companionProcess.kill('SIGTERM');
+        } else {
+          // Normal shutdown — tell companion to stop and save
+          if (companionWs && companionWs.readyState === 1) {
+            companionWs.send(JSON.stringify({ type: 'control:stop' }));
+          }
+          if (companionProcess.stdin?.writable) companionProcess.stdin.write('stop\nsave\n');
+
+          if (companionStdoutHandler) {
+            liveTranscriptPath = await Promise.race([
+              new Promise((resolvePromise) => {
+                const handler = (msg) => {
+                  if (msg.type === 'transcript:saved') {
+                    const idx = companionStdoutHandler.indexOf(handler);
+                    if (idx !== -1) companionStdoutHandler.splice(idx, 1);
+                    resolvePromise(msg.path);
+                  }
+                };
+                companionStdoutHandler.push(handler);
+              }),
+              new Promise((resolvePromise) => {
+                setTimeout(() => {
+                  warnings.push(`[WARN] ${isoNow()} Auto-saving transcript (companion did not respond within 30s)`);
+                  if (companionProcess.stdin?.writable) companionProcess.stdin.write('save\n');
+                  setTimeout(() => resolvePromise(null), 2000);
+                }, 30000);
+              }),
+            ]);
+          }
 
-  // --- Inject action timestamps into codegen output ---
-  if (existsSync(outputPath) && actionElapsedSec.length > 0) {
-    injectActionTimestamps(outputPath);
-    console.error(`Injected ${actionElapsedSec.length} action timestamp(s) into: ${outputRelative}`);
-  }
+          // Filesystem fallback
+          if (!liveTranscriptPath) {
+            const expectedPath = resolve(
+              recordingsDir || resolve(issueDir, 'recordings'),
+              `transcript-${timestamp}.json`
+            );
+            if (existsSync(expectedPath)) liveTranscriptPath = expectedPath;
+          }
 
-  // --- Voice post-processing: merge WAV segments only (transcription deferred to transcribe command) ---
-  if (voiceEnabled && segmentPaths.length > 0) {
-    try {
-      if (recording && currentRecProcess) {
-        const { stopRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
-        await stopRecording(currentRecProcess);
-        currentRecProcess = null;
-        recording = false;
+          if (companionWs) try { companionWs.close(); } catch {}
+          companionProcess.kill('SIGTERM');
+        }
+      } catch (err) {
+        warnings.push(`[ERROR] ${isoNow()} Companion shutdown error: ${err.message}`);
+        try { companionProcess.kill('SIGKILL'); } catch {}
       }
+    }
 
-      const existingSegments = segmentPaths.filter((p) => existsSync(p));
+    // --- Inject action timestamps (silent) ---
+    if (existsSync(outputPath) && actionElapsedSec.length > 0) {
+      injectActionTimestamps(outputPath);
+    }
 
-      if (existingSegments.length === 0) {
-        console.error('No audio segments recorded.');
-      } else {
-        const mergedWavPath = resolve(recordingsDir, `voice-${timestamp}.wav`);
+    // --- Voice post-processing ---
+    if (voiceEnabled && segmentPaths.length > 0) {
+      try {
+        if (recording && currentRecProcess) {
+          const { stopRecording } = await import(resolve(__dirname, 'voice', 'recorder.mjs'));
+          await stopRecording(currentRecProcess);
+          currentRecProcess = null;
+          recording = false;
+        }
 
-        if (existingSegments.length === 1) {
-          renameSync(existingSegments[0], mergedWavPath);
-        } else {
-          console.error(`Merging ${existingSegments.length} audio segments...`);
-          const args = ['--combine', 'concatenate', ...existingSegments, mergedWavPath];
-          execSync(`sox ${args.map((a) => `"${a}"`).join(' ')}`, { stdio: 'ignore' });
+        const existingSegments = segmentPaths.filter((p) => existsSync(p));
 
-          for (const seg of existingSegments) {
-            try { unlinkSync(seg); } catch {}
+        if (existingSegments.length === 0) {
+          warnings.push(`[WARN] ${isoNow()} No audio segments recorded`);
+        } else {
+          const mergedWavPath = resolve(recordingsDir, `voice-${timestamp}.wav`);
+          if (existingSegments.length === 1) {
+            renameSync(existingSegments[0], mergedWavPath);
+          } else {
+            const soxArgs = ['--combine', 'concatenate', ...existingSegments, mergedWavPath];
+            execSync(`sox ${soxArgs.map((a) => `"${a}"`).join(' ')}`, { stdio: 'ignore' });
+            for (const seg of existingSegments) {
+              try { unlinkSync(seg); } catch {}
+            }
           }
         }
+      } catch (err) {
+        warnings.push(`[ERROR] ${isoNow()} Voice processing error: ${err.message}`);
+      }
+    }
 
-        console.error(`\nVoice recording summary:`);
-        console.error(`  Audio:   ${relative(root, mergedWavPath)}`);
-        console.error(`  Codegen: ${outputRelative}`);
-        console.error(`  (Run 'transcribe' to process voice → merge into codegen)`);
+    // --- Write session metadata ---
+    if (voiceEnabled && existsSync(outputPath)) {
+      const meta = {
+        codegen: `codegen-${timestamp}.ts`,
+        audio: recordingsDir ? `recordings/voice-${timestamp}.wav` : null,
+        transcript: liveTranscriptPath ? relative(issueDir, liveTranscriptPath) : null,
+        liveTranscription: !!liveTranscriptPath,
+        engine: 'webspeech',
+        duration: null,
+        segmentCount: null,
+        tagCount: null,
+      };
+      if (liveTranscriptPath && existsSync(liveTranscriptPath)) {
+        try {
+          const transcript = JSON.parse(readFileSync(liveTranscriptPath, 'utf-8'));
+          meta.duration = transcript.duration;
+          meta.segmentCount = transcript.segments?.length ?? 0;
+          meta.tagCount = transcript.segments?.reduce((n, s) => n + (s.tags?.length ?? 0), 0) ?? 0;
+          meta.engine = transcript.engine || 'webspeech';
+        } catch {}
       }
-    } catch (err) {
-      console.error(`\nVoice processing error: ${err.message}`);
+      writeFileSync(resolve(issueDir, 'session-meta.json'), JSON.stringify(meta, null, 2));
     }
-  }
 
-  // --- Trace: inject test.use({ trace: 'on' }) and run replay to generate trace ---
-  if (existsSync(outputPath)) {
-    const codegenSrc = readFileSync(outputPath, 'utf-8');
-    if (!codegenSrc.includes("test.use({ trace: 'on' })")) {
-      const injected = codegenSrc.replace(
-        /^(import\s.*from\s+['"]@playwright\/test['"];?\s*\n)/m,
-        "$1\ntest.use({ trace: 'on' });\n",
-      );
-      if (injected !== codegenSrc) {
-        writeFileSync(outputPath, injected);
-        console.error("Injected test.use({ trace: 'on' }) into codegen output.");
+    // --- Trace injection + replay ---
+    if (existsSync(outputPath)) {
+      const codegenSrc = readFileSync(outputPath, 'utf-8');
+      if (!codegenSrc.includes("test.use({ trace: 'on' })")) {
+        const injected = codegenSrc.replace(
+          /^(import\s.*from\s+['"]@playwright\/test['"];?\s*\n)/m,
+          "$1\ntest.use({ trace: 'on' });\n",
+        );
+        if (injected !== codegenSrc) writeFileSync(outputPath, injected);
+      }
+
+      if (traceEnabled) {
+        try {
+          const replayScript = resolve(__dirname, 'trace', 'replay-with-trace.mjs');
+          execSync(`node "${replayScript}" "${outputRelative}"`, {
+            cwd: root,
+            stdio: 'inherit',
+            env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
+          });
+        } catch {
+          warnings.push(`[WARN] ${isoNow()} Trace replay failed (codegen file is still saved)`);
+        }
       }
     }
 
-    if (traceEnabled) {
-      console.error('\nStarting trace replay...');
-      try {
-        const replayScript = resolve(__dirname, 'trace', 'replay-with-trace.mjs');
-        execSync(`node "${replayScript}" "${outputRelative}"`, {
-          cwd: root,
-          stdio: 'inherit',
-          env: { ...process.env, E2E_AI_PROJECT_ROOT: root },
-        });
-      } catch {
-        console.error('Trace replay failed (codegen file is still saved).');
+    // --- Print outcome card ---
+    const hasErrors = warnings.some((w) => w.startsWith('[ERROR]'));
+    const hasWarnings = warnings.length > 0;
+    const metaPath = relative(root, resolve(issueDir, 'session-meta.json'));
+
+    if (code === 0 && !hasErrors) {
+      const successItems = [{ label: 'Details', value: metaPath }];
+      if (hasWarnings) {
+        const logPath = saveErrorLog(issueDir, 'record-error.log', warnings);
+        if (logPath) successItems.push({ label: 'Warnings', value: relative(root, logPath) });
       }
+      successItems.push({ label: 'Next', value: `levante transcribe --key ${issueKey}` });
+      if (harPath && existsSync(harPath)) {
+        successItems.push({ label: 'HAR', value: relative(root, harPath) });
+      }
+      printSuccess('Session saved', successItems);
+    } else {
+      const firstError = warnings.find((w) => w.startsWith('[ERROR]'));
+      const primaryMsg = firstError
+        ? firstError.replace(/^\[ERROR\] \S+ /, '')
+        : `Recording exited with code ${code}`;
+      const logEntries = warnings.length
+        ? warnings
+        : [`[ERROR] ${isoNow()} Recording exited with code ${code}`];
+      const logPath = saveErrorLog(issueDir, 'record-error.log', logEntries);
+      const errorItems = [];
+      if (logPath) errorItems.push({ label: 'Log', value: relative(root, logPath) });
+      const hint = getFixHint(primaryMsg, issueKey);
+      if (hint) errorItems.push({ label: 'Fix', value: hint });
+      printError(primaryMsg, errorItems);
     }
-  }
 
-  if (harPath && existsSync(harPath)) {
-    console.error(`HAR saved: ${relative(root, harPath)}`);
+  } catch (fatalErr) {
+    warnings.push(`[ERROR] ${isoNow()} Fatal exit handler error: ${fatalErr.message}`);
+    const logPath = saveErrorLog(issueDir, 'record-error.log', warnings);
+    printError(fatalErr.message, logPath ? [{ label: 'Log', value: relative(root, logPath) }] : []);
   }
 
   process.exit(code ?? 0);

package/scripts/companion/open-url.mjs

@@ -0,0 +1,20 @@
+import { spawn } from 'node:child_process';
+
+export function openUrl(url) {
+  const platform = process.platform;
+  let cmd, args;
+
+  if (platform === 'darwin') {
+    cmd = 'open';
+    args = [url];
+  } else if (platform === 'win32') {
+    cmd = 'cmd';
+    args = ['/c', 'start', '', url];
+  } else {
+    cmd = 'xdg-open';
+    args = [url];
+  }
+
+  const child = spawn(cmd, args, { stdio: 'ignore', detached: true });
+  child.unref();
+}