@build-astron-co/nimbus 0.2.0 → 0.4.0

package/src/cli/run.ts

@@ -9,6 +9,7 @@
  *   nimbus run "fix the failing tests" --auto-approve
  *   echo "analyze this repo" | nimbus run --stdin
  *   nimbus run "estimate costs" --format json --model anthropic/claude-haiku-4-5
+ *   nimbus run --schema   # print the JSON output schema and exit
  */
 
 import { runAgentLoop } from '../agent/loop';
@@ -18,23 +19,83 @@ import { standardTools } from '../tools/schemas/standard';
 import { devopsTools } from '../tools/schemas/devops';
 import type { AgentMode } from '../agent/system-prompt';
 import type { LLMRouter } from '../llm/router';
+import { expandFileReferences } from '../agent/expand-files';
+
+/** JSON output schema for `nimbus run --format json` */
+export interface RunJsonOutput {
+  success: boolean;       // whether the agent completed without error
+  output: string;         // final text response from the agent
+  cost: number;           // total cost in USD
+  turns: number;          // number of LLM turns taken
+  toolCalls: Array<{      // all tool calls made during the run
+    name: string;
+    success: boolean;
+    durationMs: number;
+  }>;
+  errors: string[];       // any error messages encountered
+  /** L2: Terraform plan summary extracted from plan output (CI-friendly) */
+  planSummary?: {
+    toAdd: number;
+    toChange: number;
+    toDestroy: number;
+    raw: string;
+  };
+  /** M3: Summary of DevOps tools invoked during the run */
+  devops_summary?: {
+    tools_used: string[];
+    tool_call_count: number;
+    devops_tool_count: number;
+  };
+  /** M1: Infrastructure context active during the run */
+  infraContext?: {
+    terraformWorkspace?: string;
+    kubectlContext?: string;
+    awsAccount?: string;
+  };
+  /** M1: Unique DevOps tool names invoked */
+  toolsUsed?: string[];
+}
 
 /** Options parsed from command-line arguments */
 export interface RunOptions {
   /** The prompt to execute */
   prompt: string;
   /** Output format */
-  format: 'text' | 'json';
-  /** Skip permission prompts — auto-approve everything */
+  format: 'text' | 'json' | 'table';
+  /** Skip permission prompts — auto-approve everything (--non-interactive is an alias) */
   autoApprove: boolean;
   /** Read prompt from stdin */
   stdin: boolean;
+  /** Parse stdin as JSON config object { prompt, mode, model, autoApprove, maxTurns } */
+  stdinJson: boolean;
   /** Model override */
   model?: string;
   /** Agent mode override */
   mode: AgentMode;
   /** Maximum turns */
   maxTurns: number;
+  /** G13: Abort agent loop after this many milliseconds */
+  timeout?: number;
+  /** G15: Print last tool output as JSON instead of prose */
+  rawToolOutput?: boolean;
+  /** G23: Print the JSON output schema and exit */
+  schema?: boolean;
+  /** M1: Dry-run mode — forces plan mode and instructs agent not to mutate anything */
+  dryRun?: boolean;
+  /** H3: Exit with code 1 on agent failure */
+  exitOnError?: boolean;
+  /** H3: kubectl context to inject before running */
+  context?: string;
+  /** H3: Terraform workspace to inject before running */
+  workspace?: string;
+  /** H3: Kubernetes namespace to inject before running */
+  namespace?: string;
+  /** H3: Webhook URL to POST result to after completion */
+  notify?: string;
+  /** H3: Slack webhook URL to POST formatted result to */
+  notifySlack?: string;
+  /** G16: Maximum cost in USD per session */
+  budget?: number;
 }
 
 /** Result of a non-interactive run */
@@ -62,12 +123,24 @@ export interface RunResult {
  */
 export function parseRunArgs(args: string[]): RunOptions {
   let prompt = '';
-  let format: 'text' | 'json' = 'text';
+  let format: 'text' | 'json' | 'table' = 'text';
   let autoApprove = false;
   let stdin = false;
+  let stdinJson = false;
   let model: string | undefined;
   let mode: AgentMode = 'build';
   let maxTurns = 50;
+  let timeout: number | undefined;
+  let rawToolOutput = false;
+  let schema = false;
+  let dryRun = false;
+  let exitOnError = true; // C5: default true for CI/CD POSIX convention
+  let context: string | undefined;
+  let workspace: string | undefined;
+  let namespace: string | undefined;
+  let notify: string | undefined;
+  let notifySlack: string | undefined;
+  let budget: number | undefined;
 
   const positional: string[] = [];
 
@@ -76,18 +149,23 @@ export function parseRunArgs(args: string[]): RunOptions {
 
     switch (arg) {
       case '--format':
-        format = (args[++i] ?? 'text') as 'text' | 'json';
+        format = (args[++i] ?? 'text') as 'text' | 'json' | 'table';
         break;
       case '--json':
         format = 'json';
         break;
       case '--auto-approve':
       case '-y':
+      case '--non-interactive':
         autoApprove = true;
         break;
       case '--stdin':
         stdin = true;
         break;
+      case '--stdin-json':
+        stdinJson = true;
+        stdin = true; // also read stdin
+        break;
       case '--model':
         model = args[++i];
         break;
@@ -97,6 +175,60 @@ export function parseRunArgs(args: string[]): RunOptions {
       case '--max-turns':
         maxTurns = parseInt(args[++i] ?? '50', 10);
         break;
+      case '--timeout':
+        // G13: timeout in seconds, converted to ms
+        timeout = parseInt(args[++i] ?? '0', 10) * 1000;
+        break;
+      case '--raw-tool-output':
+        // G15: print last tool output as JSON
+        rawToolOutput = true;
+        break;
+      case '--schema':
+        // G23: print the JSON output schema and exit
+        schema = true;
+        break;
+      case '--json-schema':
+        // GAP-16: print the stable JSON output schema and exit
+        schema = true;
+        break;
+      case '--dry-run':
+        // M1: dry-run forces plan mode — no mutations allowed
+        dryRun = true;
+        mode = 'plan';
+        break;
+      case '--exit-code-on-error':
+        // H3: exit with code 1 on failure
+        exitOnError = true;
+        break;
+      case '--no-exit-on-error':
+        // C5: legacy scripts can opt out of exit-on-error
+        exitOnError = false;
+        break;
+      case '--context':
+        // H3: kubectl context
+        context = args[++i];
+        break;
+      case '--workspace':
+        // H3: terraform workspace
+        workspace = args[++i];
+        break;
+      case '--namespace':
+      case '-n':
+        // H3: kubernetes namespace
+        namespace = args[++i];
+        break;
+      case '--notify':
+        // H3: webhook URL
+        notify = args[++i];
+        break;
+      case '--notify-slack':
+        // H3: slack webhook
+        notifySlack = args[++i];
+        break;
+      case '--budget':
+        // G16: cost budget in USD
+        budget = parseFloat(args[++i] ?? '0');
+        break;
       default:
         if (!arg.startsWith('-')) {
           positional.push(arg);
@@ -107,19 +239,71 @@ export function parseRunArgs(args: string[]): RunOptions {
 
   prompt = positional.join(' ');
 
-  return { prompt, format, autoApprove, stdin, model, mode, maxTurns };
+  return { prompt, format, autoApprove, stdin, stdinJson, model, mode, maxTurns, timeout, rawToolOutput, schema, dryRun, exitOnError, context, workspace, namespace, notify, notifySlack, budget };
 }
 
 /**
  * Execute a non-interactive run.
  */
 export async function executeRun(router: LLMRouter, options: RunOptions): Promise<RunResult> {
+  // G23 / GAP-16: --schema / --json-schema flag: print the JSON output schema and exit immediately
+  if (options.schema) {
+    const schema = {
+      type: 'object',
+      properties: {
+        success: { type: 'boolean', description: 'Whether the agent completed without error' },
+        output: { type: 'string', description: 'Final text response from the agent' },
+        cost: { type: 'number', description: 'Total cost in USD' },
+        turns: { type: 'number', description: 'Number of LLM turns taken' },
+        toolCalls: { type: 'array', items: { type: 'object', properties: { name: { type: 'string' }, success: { type: 'boolean' }, durationMs: { type: 'number' } } } },
+        errors: { type: 'array', items: { type: 'string' }, description: 'Any error messages encountered' },
+      },
+      required: ['success', 'output', 'cost', 'turns', 'toolCalls', 'errors'],
+    };
+    process.stdout.write(JSON.stringify(schema, null, 2) + '\n');
+    return {
+      success: true,
+      output: '',
+      turns: 0,
+      usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+      cost: 0,
+      interrupted: false,
+    };
+  }
+
+  // H3: Inject context/workspace/namespace into environment before agent loop
+  if (options.context) process.env.KUBECTL_CONTEXT = options.context;
+  if (options.workspace) process.env.TF_WORKSPACE = options.workspace;
+  if (options.namespace) process.env.K8S_NAMESPACE = options.namespace;
+
   // Get prompt from stdin if requested
   let prompt = options.prompt;
   if (options.stdin && !prompt) {
-    prompt = await readStdin();
+    const stdinContent = await readStdin();
+
+    // L5: --stdin-json support: parse stdin as { prompt, mode, model, autoApprove, maxTurns }
+    if (options.stdinJson && stdinContent) {
+      try {
+        const config = JSON.parse(stdinContent) as Record<string, unknown>;
+        if (typeof config.prompt === 'string') prompt = config.prompt;
+        if (config.mode === 'plan' || config.mode === 'build' || config.mode === 'deploy') {
+          options = { ...options, mode: config.mode };
+        }
+        if (typeof config.model === 'string') options = { ...options, model: config.model };
+        if (typeof config.autoApprove === 'boolean') options = { ...options, autoApprove: config.autoApprove };
+        if (typeof config.maxTurns === 'number') options = { ...options, maxTurns: config.maxTurns };
+      } catch {
+        // If JSON parse fails, treat stdin as raw prompt text
+        prompt = stdinContent;
+      }
+    } else {
+      prompt = stdinContent;
+    }
   }
 
+  // Expand @file references in the prompt
+  prompt = expandFileReferences(prompt, process.cwd());
+
   if (!prompt) {
     return {
       success: false,
@@ -149,6 +333,34 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
 
   // Collect output
   const outputParts: string[] = [];
+  const tableRows: Array<{ tool: string; status: string; output: string }> = [];
+
+  // G13: Set up timeout AbortController if --timeout was specified
+  let timeoutAbortController: AbortController | undefined;
+  let timeoutHandle: ReturnType<typeof setTimeout> | undefined;
+  if (options.timeout && options.timeout > 0) {
+    timeoutAbortController = new AbortController();
+    timeoutHandle = setTimeout(() => {
+      timeoutAbortController!.abort();
+      if (options.format === 'text') {
+        process.stderr.write(`\n[Timeout: agent loop aborted after ${options.timeout! / 1000}s]\n`);
+      }
+    }, options.timeout);
+  }
+
+  // G15: Track last tool output for --raw-tool-output
+  let lastToolName = '';
+  let lastToolOutput = '';
+
+  // G23: Track all tool calls for structured JSON output
+  const allToolCalls: Array<{ name: string; input: Record<string, unknown>; output: string; isError: boolean }> = [];
+
+  // H1: Discover infra context for CI/CD pipelines (best-effort, non-blocking)
+  let infraContext: import('../cli/init').InfraContext | undefined;
+  try {
+    const { discoverInfraContext } = await import('../cli/init');
+    infraContext = await discoverInfraContext(process.cwd());
+  } catch { /* non-critical */ }
 
   // Run the agent loop
   const result = await runAgentLoop(prompt, [], {
@@ -158,6 +370,10 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
     maxTurns: options.maxTurns,
     model: options.model,
     cwd: process.cwd(),
+    signal: timeoutAbortController?.signal,
+    dryRun: options.dryRun,
+    costBudgetUSD: options.budget,
+    infraContext,
 
     onText: text => {
       outputParts.push(text);
@@ -176,6 +392,25 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
       if (options.format === 'text' && result.isError) {
         process.stderr.write(`[Error: ${result.error}]\n`);
       }
+      if (options.format === 'table') {
+        tableRows.push({
+          tool: toolCall.name,
+          status: result.isError ? 'error' : 'ok',
+          output: (result.output ?? result.error ?? '').slice(0, 80),
+        });
+      }
+      // G15: track last tool output
+      lastToolName = toolCall.name;
+      lastToolOutput = result.isError ? (result.error ?? '') : (result.output ?? '');
+      // G23: accumulate all tool calls for structured JSON output
+      allToolCalls.push({
+        name: toolCall.name,
+        input: toolCall.input && typeof toolCall.input === 'object'
+          ? (toolCall.input as Record<string, unknown>)
+          : {},
+        output: result.isError ? (result.error ?? '') : (result.output ?? ''),
+        isError: result.isError ?? false,
+      });
     },
 
     checkPermission: async (tool, input) => {
@@ -191,11 +426,17 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
     },
   });
 
+  // G13: Clear the timeout timer if we finished before it fired
+  if (timeoutHandle) {
+    clearTimeout(timeoutHandle);
+  }
+
   const output = outputParts.join('');
 
-  // Format output
-  if (options.format === 'json') {
-    const jsonResult = {
+  // G15: --raw-tool-output: print last tool call as JSON to stdout
+  if (options.rawToolOutput && lastToolName) {
+    console.log(JSON.stringify({ tool: lastToolName, output: lastToolOutput }));
+    return {
       success: !result.interrupted,
       output,
       turns: result.turns,
@@ -203,13 +444,87 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
       cost: result.totalCost,
       interrupted: result.interrupted,
     };
+  }
+
+  // Format output
+  if (options.format === 'json') {
+    // GAP-16 / G23: structured JSON output matching the stable RunJsonOutput schema
+    // L2: Extract terraform plan summary from tool outputs for CI-friendly output
+    let planSummary: RunJsonOutput['planSummary'];
+    const tfPlanCall = allToolCalls.find(tc => tc.name === 'terraform' && tc.output && /Plan:/.test(tc.output));
+    if (tfPlanCall?.output) {
+      const planLine = tfPlanCall.output.match(/Plan:\s*(\d+)\s*to add,\s*(\d+)\s*to change,\s*(\d+)\s*to destroy/i);
+      if (planLine) {
+        planSummary = {
+          toAdd: parseInt(planLine[1]),
+          toChange: parseInt(planLine[2]),
+          toDestroy: parseInt(planLine[3]),
+          raw: planLine[0],
+        };
+      }
+    }
+    const jsonResult: RunJsonOutput = {
+      success: !result.interrupted,
+      output,
+      cost: result.totalCost ?? 0,
+      turns: result.turns ?? 0,
+      toolCalls: allToolCalls.map(tc => ({
+        name: tc.name,
+        success: !tc.isError,
+        durationMs: 0,
+      })),
+      errors: allToolCalls.filter(tc => tc.isError).map(tc => tc.output).filter(Boolean),
+      ...(planSummary ? { planSummary } : {}),
+    };
+    // M3: Build devops_summary from tool calls
+    const DEVOPS_TOOL_NAMES = new Set([
+      'terraform', 'kubectl', 'helm', 'aws', 'gcloud', 'az',
+      'docker', 'secrets', 'cicd', 'monitor', 'gitops', 'cloud_action',
+      'logs', 'certs', 'mesh', 'cfn', 'k8s_rbac', 'generate_infra',
+      'kubectl_context', 'helm_values', 'cost_estimate', 'cloud_discover',
+    ]);
+    const toolsUsed = [...new Set(allToolCalls.map(tc => tc.name))];
+    const devopsToolsUsed = toolsUsed.filter(t => DEVOPS_TOOL_NAMES.has(t));
+    if (devopsToolsUsed.length > 0) {
+      jsonResult.devops_summary = {
+        tools_used: devopsToolsUsed,
+        tool_call_count: allToolCalls.length,
+        devops_tool_count: allToolCalls.filter(tc => DEVOPS_TOOL_NAMES.has(tc.name)).length,
+      };
+    }
+    // M1: Add infraContext and toolsUsed fields
+    jsonResult.toolsUsed = toolsUsed;
+    if (infraContext) {
+      jsonResult.infraContext = {
+        terraformWorkspace: infraContext.terraformWorkspace,
+        kubectlContext: infraContext.kubectlContext,
+        awsAccount: infraContext.awsAccount,
+      };
+    }
     console.log(JSON.stringify(jsonResult, null, 2));
   } else if (options.format === 'text') {
     // Text was already streamed above
     console.log(''); // Final newline
+  } else if (options.format === 'table') {
+    // ASCII table of tool calls
+    const COL_TOOL = 30;
+    const COL_STATUS = 6;
+    const COL_OUTPUT = 80;
+    const divider = `${'-'.repeat(COL_TOOL + 2)}+${'-'.repeat(COL_STATUS + 2)}+${'-'.repeat(COL_OUTPUT + 2)}`;
+    const pad = (s: string, n: number) => s.slice(0, n).padEnd(n);
+    console.log(divider);
+    console.log(`| ${pad('Tool', COL_TOOL)} | ${pad('Status', COL_STATUS)} | ${pad('Output', COL_OUTPUT)} |`);
+    console.log(divider);
+    for (const row of tableRows) {
+      console.log(`| ${pad(row.tool, COL_TOOL)} | ${pad(row.status, COL_STATUS)} | ${pad(row.output, COL_OUTPUT)} |`);
+    }
+    console.log(divider);
+    console.log('');
+    // Also print final text output
+    if (output) process.stdout.write(output + '\n');
   }
 
-  return {
+  const runResult: RunResult = {
     success: !result.interrupted,
     output,
     turns: result.turns,
@@ -217,21 +532,97 @@ export async function executeRun(router: LLMRouter, options: RunOptions): Promis
     cost: result.totalCost,
     interrupted: result.interrupted,
   };
+
+  // H3: Fire webhook notifications after run completes
+  const duration = Date.now(); // approximate; real duration would need a start time
+  const notifyPayload = {
+    success: runResult.success,
+    output: runResult.output.slice(0, 2000), // truncate for webhook
+    cost: runResult.cost,
+    duration,
+  };
+
+  if (options.notify) {
+    try {
+      await fetch(options.notify, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(notifyPayload),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch {
+      // Webhook failure is non-fatal
+      process.stderr.write(`[Warning: notification webhook failed]\n`);
+    }
+  }
+
+  if (options.notifySlack) {
+    try {
+      const slackPayload = {
+        text: runResult.success
+          ? `:white_check_mark: *Nimbus run succeeded*\n${runResult.output.slice(0, 500)}`
+          : `:x: *Nimbus run failed*\n${runResult.output.slice(0, 500)}`,
+        attachments: [
+          {
+            fields: [
+              { title: 'Cost', value: `$${runResult.cost.toFixed(4)}`, short: true },
+              { title: 'Turns', value: String(runResult.turns), short: true },
+            ],
+          },
+        ],
+      };
+      await fetch(options.notifySlack, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(slackPayload),
+        signal: AbortSignal.timeout(10_000),
+      });
+    } catch {
+      process.stderr.write(`[Warning: Slack notification failed]\n`);
+    }
+  }
+
+  // H3: Exit with code 1 if the run failed and --exit-code-on-error is set
+  if (options.exitOnError && !runResult.success) {
+    process.exit(1);
+  }
+
+  return runResult;
 }
 
 /**
  * Read all input from stdin.
  */
 async function readStdin(): Promise<string> {
+  // If stdin is a TTY (no pipe), resolve immediately with empty string
+  if (process.stdin.isTTY) {
+    return '';
+  }
+
   const chunks: Buffer[] = [];
 
-  return new Promise(resolve => {
+  return new Promise((resolve, reject) => {
+    // 30-second timeout for stdin reads to prevent hanging
+    const timeout = setTimeout(() => {
+      process.stdin.removeAllListeners();
+      resolve(Buffer.concat(chunks).toString('utf-8').trim());
+    }, 30_000);
+
     process.stdin.on('data', chunk => chunks.push(Buffer.from(chunk)));
-    process.stdin.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8').trim()));
 
-    // If stdin is a TTY (no pipe), resolve immediately
-    if (process.stdin.isTTY) {
-      resolve('');
-    }
+    process.stdin.on('end', () => {
+      clearTimeout(timeout);
+      resolve(Buffer.concat(chunks).toString('utf-8').trim());
+    });
+
+    process.stdin.on('error', err => {
+      clearTimeout(timeout);
+      // On error, use whatever we've collected so far
+      if (chunks.length > 0) {
+        resolve(Buffer.concat(chunks).toString('utf-8').trim());
+      } else {
+        reject(err);
+      }
+    });
   });
 }

package/src/cli/serve.ts

@@ -50,6 +50,10 @@ export interface ServeOptions {
   host?: string;
   /** HTTP Basic Auth credentials in "user:pass" format. */
   auth?: string;
+  /** Run server as a background daemon (M1). */
+  background?: boolean;
+  /** Stop a running background server (M1). */
+  stop?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -198,6 +202,69 @@ export async function serveCommand(options: ServeOptions): Promise<void> {
   const port = options.port ?? 4200;
   const host = options.host ?? 'localhost';
 
+  // M1: stop a running background server
+  if (options.stop) {
+    const { join } = await import('node:path');
+    const { homedir } = await import('node:os');
+    const { readFileSync, unlinkSync, existsSync } = await import('node:fs');
+    const pidFile = join(homedir(), '.nimbus', 'serve.pid');
+    if (!existsSync(pidFile)) {
+      console.log('No background nimbus serve process found.');
+      return;
+    }
+    const pid = parseInt(readFileSync(pidFile, 'utf-8').trim(), 10);
+    try {
+      process.kill(pid, 'SIGTERM');
+      unlinkSync(pidFile);
+      console.log(`Stopped nimbus serve (PID: ${pid})`);
+    } catch (e: any) {
+      console.error(`Failed to stop process ${pid}: ${e.message}`);
+      unlinkSync(pidFile);
+    }
+    return;
+  }
+
+  // M1: daemonize — spawn detached child and exit
+  if (options.background) {
+    const { spawn } = await import('node:child_process');
+    const { join } = await import('node:path');
+    const { homedir } = await import('node:os');
+    const { writeFileSync, mkdirSync } = await import('node:fs');
+    const nimbusDir = join(homedir(), '.nimbus');
+    mkdirSync(nimbusDir, { recursive: true });
+    const childArgs = [process.argv[1], 'serve', '--port', String(port)];
+    if (options.host) childArgs.push('--host', options.host);
+    if (options.auth) childArgs.push('--auth', options.auth);
+    const child = spawn(process.execPath, childArgs, {
+      detached: true,
+      stdio: 'ignore',
+      env: process.env,
+    });
+    child.unref();
+    writeFileSync(join(nimbusDir, 'serve.pid'), String(child.pid), 'utf-8');
+    console.log(`nimbus serve started in background (PID: ${child.pid})`);
+    console.log(`Stop with: nimbus serve stop`);
+    return;
+  }
+
+  // G19: Security guard — non-localhost binding requires explicit auth
+  const isLocalhost = !host || host === 'localhost' || host === '127.0.0.1' || host === '::1';
+  if (!isLocalhost && !options.auth) {
+    throw new Error(
+      `Cannot bind nimbus serve to ${host} without authentication.\n` +
+      'Use --auth user:pass to enable HTTP Basic Auth, or bind to localhost only.'
+    );
+  }
+
+  // G19: Auto-generate token for localhost when no auth provided
+  let autoToken: string | undefined;
+  if (isLocalhost && !options.auth) {
+    const { randomBytes } = await import('node:crypto');
+    autoToken = randomBytes(16).toString('hex');
+    process.stderr.write(`\nNimbus API token: ${autoToken}\n`);
+    process.stderr.write('Pass as: Authorization: Bearer <token>\n\n');
+  }
+
   // ------------------------------------------------------------------
   // Initialize core systems
   // ------------------------------------------------------------------
@@ -220,7 +287,7 @@ export async function serveCommand(options: ServeOptions): Promise<void> {
     })
   );
 
-  // Optional HTTP Basic Auth
+  // HTTP Basic Auth (explicit or auto-generated token)
   if (options.auth) {
     const colonIdx = options.auth.indexOf(':');
     if (colonIdx > 0) {
@@ -228,6 +295,16 @@ export async function serveCommand(options: ServeOptions): Promise<void> {
       const pass = options.auth.slice(colonIdx + 1);
       app.onBeforeHandle(createAuthMiddleware({ username: user, password: pass }));
     }
+  } else if (autoToken) {
+    // G19: Bearer token auth for localhost when no explicit auth provided
+    const capturedToken = autoToken;
+    app.onBeforeHandle((ctx: any) => {
+      const authHeader = (ctx.request as Request).headers.get('Authorization') ?? '';
+      if (authHeader !== `Bearer ${capturedToken}`) {
+        ctx.set.status = 401;
+        return { error: 'Unauthorized. Pass Authorization: Bearer <token>' };
+      }
+    });
   }
 
   // ------------------------------------------------------------------

package/src/cli/web.ts

@@ -23,6 +23,8 @@ export interface WebOptions {
   auth?: string;
   /** URL of the Web UI (default: http://localhost:6001/nimbus). */
   uiUrl?: string;
+  /** Skip opening browser (L3). */
+  noOpen?: boolean;
 }
 
 /**
@@ -51,12 +53,14 @@ export async function webCommand(options: WebOptions): Promise<void> {
   console.log(`Starting Nimbus API server on port ${port}...`);
   console.log(`Opening Web UI at ${uiUrl}\n`);
 
-  // Open browser after a short delay to let the server start
-  setTimeout(() => {
-    openBrowser(uiUrl).catch(() => {
-      console.log(`Could not open browser. Please visit: ${uiUrl}`);
-    });
-  }, 1500);
+  // Open browser after a short delay to let the server start (skipped with --no-open)
+  if (!options.noOpen) {
+    setTimeout(() => {
+      openBrowser(uiUrl).catch(() => {
+        console.log(`Could not open browser. Please visit: ${uiUrl}`);
+      });
+    }, 1500);
+  }
 
   // Start the server (this blocks)
   await serveCommand({