fix: clarify sandboxed local server failures

Fixes #168.

Author: blimmer

packages/cli/src/annotation/runAnnotation.test.ts

@@ -3,7 +3,7 @@ import { createDeferred } from '@contextbridge/shared/testHelpers';
 import { describe, expect, it } from 'bun:test';
 import { annotationArgs, environment } from '#src/testFactories.ts';
 import { createAnnotationDependencies, createStubContext } from '#src/testHelpers/index.ts';
-import { runAnnotation } from './runAnnotation.ts';
+import { AnnotationEnvironmentError, runAnnotation } from './runAnnotation.ts';
 
 describe('runAnnotation', () => {
   it('opens the browser and returns the submitted review', async () => {
@@ -68,6 +68,49 @@ describe('runAnnotation', () => {
     expect(analytics.captures.some((c) => c.event === 'plan_review_submitted')).toBe(false);
   });
 
+  it('maps the port-0 Bun bind failure to an annotation environment error', async () => {
+    const { context } = createStubContext();
+    const deps = createAnnotationDependencies();
+    const cause = Object.assign(new Error('Failed to start server. Is port 0 in use?'), { code: 'EADDRINUSE' });
+    deps.startReviewServer = () => {
+      throw cause;
+    };
+
+    const caught = await runAnnotation(context, annotationArgs.build(), deps).then(
+      () => null,
+      (e: unknown) => e,
+    );
+
+    expect(caught).toBeInstanceOf(AnnotationEnvironmentError);
+    expect((caught as AnnotationEnvironmentError).cause).toBe(cause);
+    expect((caught as AnnotationEnvironmentError).message).toContain('network sandbox');
+    expect(deps.closeCount).toBe(0);
+  });
+
+  it('keeps explicit-port EADDRINUSE failures as regular runtime failures', () => {
+    const { context } = createStubContext();
+    const deps = createAnnotationDependencies();
+    const cause = Object.assign(new Error('Failed to start server. Is port 3456 in use?'), { code: 'EADDRINUSE' });
+    deps.startReviewServer = () => {
+      throw cause;
+    };
+
+    expect(runAnnotation(context, annotationArgs.build({ port: 3456 }), deps)).rejects.toBe(cause);
+    expect(deps.closeCount).toBe(0);
+  });
+
+  it('keeps CONTEXTBRIDGE_PORT EADDRINUSE failures as regular runtime failures', () => {
+    const { context } = createStubContext({ env: environment.build({ CONTEXTBRIDGE_PORT: 3456 }) });
+    const deps = createAnnotationDependencies();
+    const cause = Object.assign(new Error('Failed to start server. Is port 3456 in use?'), { code: 'EADDRINUSE' });
+    deps.startReviewServer = () => {
+      throw cause;
+    };
+
+    expect(runAnnotation(context, annotationArgs.build(), deps)).rejects.toBe(cause);
+    expect(deps.closeCount).toBe(0);
+  });
+
   it('closes the server and rejects when SIGINT is received', async () => {
     const { context, analytics } = createStubContext();
     const result = createDeferred<AnnotationSubmission>();

packages/cli/src/annotation/runAnnotation.ts

@@ -7,6 +7,7 @@ import type {
   AnnotationSubmission,
   ContentKind,
 } from '@contextbridge/shared/annotationSchema';
+import { getErrorMessage, hasErrorCode } from '@contextbridge/shared/errors';
 import type { FrontendConfig } from '@contextbridge/shared/frontendConfigSchema';
 import { nowInstant } from '@contextbridge/shared/time';
 import type { UpdateNotice } from '@contextbridge/shared/updateNoticeSchema';
@@ -20,6 +21,16 @@ export class AnnotationInterruptedError extends Error {
   }
 }
 
+export class AnnotationEnvironmentError extends Error {
+  constructor(cause: unknown) {
+    super(
+      'ContextBridge could not start its local browser server. Your coding harness may be running contextbridge in a network sandbox that blocks localhost. Allow local network access for contextbridge or run it outside the sandbox, then try again.',
+      { cause },
+    );
+    this.name = 'AnnotationEnvironmentError';
+  }
+}
+
 export interface RunAnnotationArgs {
   content: string;
   contentKind: ContentKind;
@@ -80,13 +91,20 @@ export async function runAnnotation(
     const htmlPromise = deps.loadHtml();
     htmlPromise.catch((err: unknown) => logger.error({ err }, 'failed to load annotation UI bundle'));
 
-    server = deps.startReviewServer(ctx, {
-      html: htmlPromise,
-      payload,
-      config: frontendConfig,
-      port,
-      checkForUpdate: () => updater.checkForUpdate().catch(() => null),
-    });
+    try {
+      server = deps.startReviewServer(ctx, {
+        html: htmlPromise,
+        payload,
+        config: frontendConfig,
+        port,
+        checkForUpdate: () => updater.checkForUpdate().catch(() => null),
+      });
+    } catch (err) {
+      if (isLikelyLocalServerNetworkSandboxError(err, port ?? 0)) {
+        throw new AnnotationEnvironmentError(err);
+      }
+      throw err;
+    }
     removeSigintHandler = deps.registerSigintHandler(() => {
       if (sigintHandled) {
         return;
@@ -122,6 +140,14 @@ export async function runAnnotation(
   }
 }
 
+export function isLikelyLocalServerNetworkSandboxError(err: unknown, port: number): boolean {
+  if (hasErrorCode(err, 'EACCES') || hasErrorCode(err, 'EPERM')) {
+    return true;
+  }
+
+  return port === 0 && hasErrorCode(err, 'EADDRINUSE') && getErrorMessage(err).includes('port 0');
+}
+
 const defaultAnnotationDependencies: AnnotationDependencies = {
   loadHtml: () => import('./bundledAnnotationHtml.ts').then((m) => m.bundledAnnotationHtml),
   startReviewServer: (ctx, { html, payload, config, port, checkForUpdate }) =>

packages/cli/src/commands/abort.ts

@@ -2,14 +2,20 @@ import { CommanderError } from 'commander';
 import type { CliContext } from '#src/context.ts';
 
 /**
- * Log and throw a CommanderError for a user-recoverable ('input') or runtime
- * failure inside a subcommand handler.
+ * Log and throw a CommanderError for a user-recoverable ('input' or 'environment')
+ * or runtime failure inside a subcommand handler.
  */
-export function abort(ctx: CliContext, command: string, kind: 'input' | 'runtime', message: string): never {
+export function abort(
+  ctx: CliContext,
+  command: string,
+  kind: 'input' | 'runtime' | 'environment',
+  message: string,
+): never {
   const { logger } = ctx;
-  // 'input' is user-recoverable — logged at warn so Sentry's pinoIntegration
-  // (error/fatal only) doesn't forward it. 'runtime' is a genuine failure.
-  if (kind === 'input') {
+  // 'input' and 'environment' are user-recoverable — logged at warn so Sentry's
+  // pinoIntegration (error/fatal only) doesn't forward them. 'runtime' is a
+  // genuine failure.
+  if (kind === 'input' || kind === 'environment') {
     logger.warn(message);
   } else {
     logger.error(message);

packages/cli/src/commands/hookClaude.ts

@@ -1,9 +1,10 @@
 import type { AnnotationSubmission } from '@contextbridge/shared/annotationSchema';
 import { getErrorMessage } from '@contextbridge/shared/errors';
 import { type Command, CommanderError } from 'commander';
-import { type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
+import { AnnotationEnvironmentError, type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
 import type { CliContext } from '#src/context.ts';
 import { type ClaudeHookResponse, claudeHookResponse } from '#src/formatters/plan/claudeHookResponse.ts';
+import { abort as abortCommand } from './abort.ts';
 import { type ClaudeHookPayload, ClaudeHookPayloadSchema } from './claudeHookSchema.ts';
 
 export interface HookClaudeDependencies {
@@ -97,6 +98,9 @@ async function handleExitPlanMode(
   try {
     submission = await runReview(ctx, { content: planContent, contentKind: 'plan', entrypoint: 'hook_claude' });
   } catch (err) {
+    if (err instanceof AnnotationEnvironmentError) {
+      abortCommand(ctx, 'hookClaude', 'environment', err.message);
+    }
     abort(ctx, 'runtime', getErrorMessage(err));
   }
 

packages/cli/src/commands/hookCodex.test.ts

@@ -2,15 +2,20 @@ import type { AnnotationSubmission } from '@contextbridge/shared/annotationSchem
 import { annotationSubmission } from '@contextbridge/shared/testFactories';
 import { describe, expect, it } from 'bun:test';
 import { CommanderError } from 'commander';
-import { type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
+import { AnnotationEnvironmentError, type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
 import type { CodexStopResponse } from '#src/formatters/plan/codexStopResponse.ts';
 import {
   annotationArgs,
   codexStopHookPayload,
   codexTranscriptHookPromptLine,
   codexTranscriptPlanLine,
 } from '#src/testFactories.ts';
-import { createAnnotationDependencies, createStubContext, readErrorLogs } from '#src/testHelpers/index.ts';
+import {
+  createAnnotationDependencies,
+  createStubContext,
+  readErrorLogs,
+  readWarnLogs,
+} from '#src/testHelpers/index.ts';
 import type { CodexStopHookPayload } from './codexHookSchema.ts';
 import { type HookCodexDependencies, extractLatestPlanFromTranscript, runHookCodex } from './hookCodex.ts';
 
@@ -100,6 +105,32 @@ describe('hookCodex handler', () => {
     expect(readErrorLogs(logs).some((r) => r.msg.includes('failed to read codex transcript'))).toBe(true);
   });
 
+  it('surfaces local network sandbox failures without error-level logs', async () => {
+    const { context, io, logs } = createStubContext();
+    const deps = createHookDependencies({
+      transcript: transcriptWithPlan('# Plan\n'),
+      runReview: () =>
+        Promise.reject(
+          new AnnotationEnvironmentError(
+            Object.assign(new Error('Failed to start server. Is port 0 in use?'), { code: 'EADDRINUSE' }),
+          ),
+        ),
+    });
+    writeStopPayload(io, { transcript_path: '/tmp/codex-transcript.jsonl', last_assistant_message: null });
+
+    const caught = await runHookCodex(context, deps).then(
+      () => null,
+      (e: unknown) => e,
+    );
+
+    expect(caught).toBeInstanceOf(CommanderError);
+    expect((caught as CommanderError).code).toBe('contextbridge.hookCodex.environmentError');
+    expect((caught as CommanderError).message).toContain('network sandbox');
+    expect(io.stdout.text()).toBe('');
+    expect(readWarnLogs(logs).some((r) => r.msg.includes('network sandbox'))).toBe(true);
+    expect(readErrorLogs(logs)).toEqual([]);
+  });
+
   it('reviews an approved proposed_plan tag from last_assistant_message without reading the transcript', async () => {
     const { context, io } = createStubContext();
     const deps = createHookDependencies({

packages/cli/src/commands/hookCodex.ts

@@ -3,9 +3,10 @@ import { getErrorMessage, toError } from '@contextbridge/shared/errors';
 import { safeJsonParse } from '@contextbridge/shared/json';
 import { type Command, CommanderError } from 'commander';
 import { ResultAsync, err, ok } from 'neverthrow';
-import { type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
+import { AnnotationEnvironmentError, type RunAnnotationArgs, runAnnotation } from '#src/annotation/runAnnotation.ts';
 import type { CliContext } from '#src/context.ts';
 import { type CodexStopResponse, codexStopResponse } from '#src/formatters/plan/codexStopResponse.ts';
+import { abort as abortCommand } from './abort.ts';
 import {
   type CodexStopHookPayload,
   CodexStopHookPayloadSchema,
@@ -109,7 +110,12 @@ async function handleStop(
     toError,
   ).match(
     (submission: AnnotationSubmission) => codexStopResponse(submission, planContent),
-    (e) => abort(ctx, 'runtime', getErrorMessage(e)),
+    (e) => {
+      if (e instanceof AnnotationEnvironmentError) {
+        abortCommand(ctx, 'hookCodex', 'environment', e.message);
+      }
+      abort(ctx, 'runtime', getErrorMessage(e));
+    },
   );
 }
 

packages/cli/src/commands/open.ts

@@ -3,6 +3,7 @@ import { getErrorMessage } from '@contextbridge/shared/errors';
 import { type Command, CommanderError } from 'commander';
 import {
   type AnnotationDependencies,
+  AnnotationEnvironmentError,
   AnnotationInterruptedError,
   runAnnotation,
 } from '#src/annotation/runAnnotation.ts';
@@ -56,6 +57,9 @@ export async function runOpen(ctx: CliContext, args: OpenArgs, deps?: Annotation
       logger.info('open session interrupted');
       throw new CommanderError(130, 'contextbridge.open.sigint', 'open session interrupted');
     }
+    if (err instanceof AnnotationEnvironmentError) {
+      abort(ctx, 'open', 'environment', err.message);
+    }
     abort(ctx, 'open', 'runtime', getErrorMessage(err));
   }
 }

packages/cli/src/commands/plan.test.ts

@@ -112,6 +112,28 @@ describe('plan handler', () => {
     expect(readErrorLogs(logs).some((r) => r.msg.includes('open failed'))).toBe(true);
   });
 
+  it('surfaces local network sandbox bind failures without error-level logs', async () => {
+    const { context, io, logs } = createStubContext();
+    const deps = createAnnotationDependencies();
+    deps.startReviewServer = () => {
+      throw Object.assign(new Error('Failed to start server. Is port 0 in use?'), { code: 'EADDRINUSE' });
+    };
+    io.stdin.write('# Plan\n');
+    io.stdin.end();
+
+    const caught = await runPlan(context, {}, deps).then(
+      () => null,
+      (e: unknown) => e,
+    );
+
+    expect(caught).toBeInstanceOf(CommanderError);
+    expect((caught as CommanderError).code).toBe('contextbridge.plan.environmentError');
+    expect((caught as CommanderError).message).toContain('network sandbox');
+    expect(io.stdout.text()).toBe('');
+    expect(readWarnLogs(logs).some((r) => r.msg.includes('network sandbox'))).toBe(true);
+    expect(readErrorLogs(logs)).toEqual([]);
+  });
+
   it('closes the server and exits cleanly (without error-level logs) when SIGINT is received', async () => {
     const { context, io, logs } = createStubContext();
     const deps = createAnnotationDependencies({ result: createDeferred<AnnotationSubmission>().promise });

packages/cli/src/commands/plan.ts

@@ -2,6 +2,7 @@ import { getErrorMessage } from '@contextbridge/shared/errors';
 import { type Command, CommanderError, InvalidArgumentError } from 'commander';
 import {
   type AnnotationDependencies,
+  AnnotationEnvironmentError,
   AnnotationInterruptedError,
   runAnnotation,
 } from '#src/annotation/runAnnotation.ts';
@@ -55,6 +56,9 @@ export async function runPlan(ctx: CliContext, args: PlanArgs, deps?: Annotation
       logger.info('plan review interrupted');
       throw new CommanderError(130, 'contextbridge.plan.sigint', 'plan review interrupted');
     }
+    if (err instanceof AnnotationEnvironmentError) {
+      abort(ctx, 'plan', 'environment', err.message);
+    }
     abort(ctx, 'plan', 'runtime', getErrorMessage(err));
   }
 }