@pellux/goodvibes-agent 0.1.86 → 0.1.88

package/CHANGELOG.md

@@ -2,6 +2,14 @@
 
 All notable changes to GoodVibes Agent will be recorded here.
 
+## 0.1.88 - 2026-06-01
+
+- e97d2a2 Fix release test daemon port allocation
+
+## 0.1.87 - 2026-06-01
+
+- cd0d9fc Improve Agent TUI startup diagnostics
+
 ## 0.1.86 - 2026-06-01
 
 - aac1849 Retry npm publish verification

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pellux/goodvibes-agent",
-  "version": "0.1.86",
+  "version": "0.1.88",
   "private": false,
   "description": "GoodVibes personal operator assistant TUI with a proactive Agent product brain, isolated Agent Knowledge, local profiles, routines, skills, personas, and explicit build delegation.",
   "type": "module",

package/src/cli/tui-startup.ts

@@ -9,6 +9,70 @@ export type InteractiveTerminalCheckInput = {
   readonly stdoutIsTTY: boolean | undefined;
 };
 
+type NodeLikeError = Error & {
+  readonly code?: string;
+  readonly path?: string;
+  readonly syscall?: string;
+};
+
+export type FatalStartupFormatOptions = {
+  readonly binary: string;
+  readonly debug?: boolean;
+};
+
+function isNodeLikeError(error: unknown): error is NodeLikeError {
+  return error instanceof Error;
+}
+
+function fatalStartupMessage(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  try {
+    return JSON.stringify(error);
+  } catch {
+    return String(error);
+  }
+}
+
+function fatalStartupStack(error: unknown): string {
+  if (error instanceof Error) return error.stack ?? error.message;
+  return fatalStartupMessage(error);
+}
+
+export function formatFatalStartupErrorForLog(error: unknown): string {
+  return fatalStartupStack(error);
+}
+
+export function formatFatalStartupErrorForUser(error: unknown, options: FatalStartupFormatOptions): string {
+  if (options.debug === true) return fatalStartupStack(error);
+
+  const message = fatalStartupMessage(error);
+  if (isNodeLikeError(error) && (error.code === 'EACCES' || error.code === 'EPERM')) {
+    return [
+      `${options.binary} could not prepare its local workspace or log directory.`,
+      error.path ? `  path: ${error.path}` : '',
+      error.syscall ? `  operation: ${error.syscall}` : '',
+      '  reason: permission denied',
+      `  next: launch from a writable directory, pass '${options.binary} --cd <dir>', or set GOODVIBES_WORKING_DIR to a writable path.`,
+      '  note: GOODVIBES_AGENT_HOME can be set to move Agent-local config, sessions, memory, skills, personas, and routines.',
+    ].filter((line) => line.length > 0).join('\n');
+  }
+
+  if (isNodeLikeError(error) && error.code === 'ENOENT') {
+    return [
+      `${options.binary} could not find a required startup path.`,
+      error.path ? `  path: ${error.path}` : '',
+      `  reason: ${message}`,
+      `  next: check '${options.binary} --cd <dir>' and GOODVIBES_WORKING_DIR, then rerun '${options.binary} status'.`,
+    ].filter((line) => line.length > 0).join('\n');
+  }
+
+  return [
+    message || `${options.binary} failed during startup.`,
+    'Set GOODVIBES_AGENT_DEBUG=1 to print a stack trace.',
+  ].join('\n');
+}
+
 export function getInteractiveTerminalLaunchError(input: InteractiveTerminalCheckInput): string | null {
   const stdinReady = input.stdinIsTTY === true;
   const stdoutReady = input.stdoutIsTTY === true;

package/src/main.ts

@@ -45,7 +45,7 @@ import { deriveComposerState } from './core/composer-state.ts';
 import { buildPersistedSessionContext, formatReturnContextForDisplay, getReturnContextMode, maybeAssistReturnContextSummary } from '@/runtime/index.ts';
 import { summarizeError } from '@pellux/goodvibes-sdk/platform/utils';
 import { prepareShellCliRuntime } from './cli/entrypoint.ts';
-import { applyInitialTuiCliState, getInteractiveTerminalLaunchError } from './cli/tui-startup.ts';
+import { applyInitialTuiCliState, formatFatalStartupErrorForLog, formatFatalStartupErrorForUser, getInteractiveTerminalLaunchError } from './cli/tui-startup.ts';
 import { wireSpokenTurnRuntime } from './audio/spoken-turn-wiring.ts';
 import { attachSpokenTurnModelRouting, createSpokenTurnInputOptions } from './audio/spoken-turn-model-routing.ts';
 import { allowTerminalWrite, installTuiTerminalOutputGuard } from './runtime/terminal-output-guard.ts';
@@ -768,29 +768,19 @@ async function main() {
 
 }
 
-function formatFatalStartupError(error: unknown): string {
-  if (error instanceof Error) {
-    return error.stack ?? error.message;
-  }
-  if (typeof error === 'string') {
-    return error;
-  }
-  try {
-    return JSON.stringify(error);
-  } catch {
-    return String(error);
-  }
-}
-
 main().catch((err: unknown) => {
-  const detail = formatFatalStartupError(err);
+  const detail = formatFatalStartupErrorForLog(err);
   try {
     logger.error('Fatal error', { error: detail });
   } catch {
     // Startup diagnostics must never hide the original launch failure.
   }
+  const userDetail = formatFatalStartupErrorForUser(err, {
+    binary: 'goodvibes-agent',
+    debug: process.env['GOODVIBES_AGENT_DEBUG'] === '1',
+  });
   try {
-    process.stderr.write(`goodvibes-agent failed to launch:\n${detail}\n`);
+    process.stderr.write(`goodvibes-agent failed to launch:\n${userDetail}\n`);
   } catch {
     // Ignore secondary stderr failures during process teardown.
   }

package/src/version.ts

@@ -6,7 +6,7 @@ import { join } from 'node:path';
 // The prebuild script updates the fallback value before compilation.
 // Uses import.meta.dir (Bun) to locate package.json relative to this file,
 // which is correct regardless of the process working directory.
-let _version = '0.1.86';
+let _version = '0.1.88';
 let _sdkVersion = '0.33.35';
 try {
   const pkg = JSON.parse(readFileSync(join(import.meta.dir, '..', 'package.json'), 'utf-8')) as {