@bahulam/code 2.6.0 → 2.6.2

package/src/core/bundled-runtime.mjs

@@ -0,0 +1,348 @@
+/**
+ * Bundled Python runtime adapter (PRD-091 §6.3).
+ *
+ * The Bahulam Code CLI ships with a bundled Python `agent_framework`
+ * runtime — the SAME code the cloud/enterprise backend runs. This module
+ * spawns that runtime as a subprocess, waits for READY, and provides a
+ * `fetch`-like helper for the rest of the CLI to talk to it over a Unix
+ * socket.
+ *
+ * Contract: the runtime speaks the same HTTP/SSE vocabulary the cloud
+ * backend does (POST /api/execute, POST /api/callback/{task_id}, POST
+ * /api/intervention/{task_id}, GET /healthz). So stream-client.mjs can
+ * swap between "local runtime" and "cloud backend" by changing the
+ * `baseUrl` — everything else stays identical.
+ *
+ * Lifecycle:
+ *   1. First call to ensureRuntimeReady() spawns bahulam-agent as a
+ *      subprocess with a per-session Unix socket path.
+ *   2. Waits for /healthz to return {status:'ready'} (up to READY_TIMEOUT_MS).
+ *   3. Returns a `socketPath` the caller uses with runtimeFetch().
+ *   4. Subsequent calls reuse the warm daemon (no re-spawn cost).
+ *   5. Process exit tears down the subprocess cleanly.
+ *
+ * Fallbacks:
+ *   - BAHULAM_JS_AGENT=1 → callers should bypass this module entirely
+ *     and use the interim LocalAgent JS class.
+ *   - BAHULAM_RUNTIME_ROOT=<path> → override the default install location
+ *     (~/.bahulam/runtime/current) for dev/CI.
+ *   - Windows: Unix sockets are not universal; falls back to a random
+ *     localhost TCP port. The runtime supports --port for this reason.
+ *
+ * See PRD-090 §4a (Monetization Model) for the three-path routing that
+ * lives INSIDE the runtime; this adapter is transport-only.
+ */
+
+import { spawn, spawnSync } from 'node:child_process';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import * as net from 'node:net';
+import * as http from 'node:http';
+
+const DEFAULT_RUNTIME_ROOT = path.join(os.homedir(), '.bahulam', 'runtime', 'current');
+const READY_TIMEOUT_MS = 30_000;
+const READY_POLL_MS = 100;
+const IS_WINDOWS = process.platform === 'win32';
+
+// TCP is the default transport so existing fetch-based call sites in
+// stream-client.mjs work unchanged (baseUrl points at http://127.0.0.1:<port>).
+// Unix socket is available via BAHULAM_RUNTIME_TRANSPORT=socket for stricter
+// isolation but requires an undici dispatcher path for every fetch.
+const USE_UNIX_SOCKET = process.env.BAHULAM_RUNTIME_TRANSPORT === 'socket';
+
+let _daemon = null; // { proc, socketPath, port, ready }
+
+function _runtimeRoot() {
+  return process.env.BAHULAM_RUNTIME_ROOT || DEFAULT_RUNTIME_ROOT;
+}
+
+function _runtimeBin() {
+  return path.join(_runtimeRoot(), 'bin', IS_WINDOWS ? 'bahulam-agent.exe' : 'bahulam-agent');
+}
+
+// Read the framework LICENSE_KEY from a config file so shipped end-users
+// don't have to set an env var. Precedence: env var wins if already set,
+// otherwise read ~/.bahulam/license.jwt. Returns null when neither is set.
+function _readLicenseKey() {
+  if (process.env.LICENSE_KEY) return process.env.LICENSE_KEY;
+  const licensePath = path.join(os.homedir(), '.bahulam', 'license.jwt');
+  try {
+    return fs.readFileSync(licensePath, 'utf8').trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+// Read the saved bahulam CLI token from ~/.bahulam/config.json so the
+// bundled Python runtime authenticates to gateway.bahulam.ai as the
+// logged-in user without the shell having to export BAHULAM_API_KEY.
+// Precedence: shell env wins > saved config. Returns null when neither
+// is present (framework then errors with an "Not logged in" style message).
+function _readCliToken() {
+  if (process.env.BAHULAM_API_KEY) return process.env.BAHULAM_API_KEY;
+  if (process.env.BAHULAM_CLI_TOKEN) return process.env.BAHULAM_CLI_TOKEN;
+  if (process.env.B0_TOKEN) return process.env.B0_TOKEN;
+  const configPath = path.join(os.homedir(), '.bahulam', 'config.json');
+  try {
+    const raw = fs.readFileSync(configPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    const token = (parsed && typeof parsed.token === 'string') ? parsed.token.trim() : null;
+    return token || null;
+  } catch {
+    return null;
+  }
+}
+
+function _newSocketPath() {
+  const dir = path.join(os.tmpdir(), 'bahulam-code');
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, `agent-${randomBytes(4).toString('hex')}.sock`);
+}
+
+// Remove the framework's license lock + keychain-shadow so activation
+// re-runs fresh on the next import. All calls are best-effort — a missing
+// file is fine, a locked keychain is fine.
+function _clearLicenseActivationState() {
+  const paths = [
+    path.join(os.homedir(), '.agent_framework', '.license_lock'),
+    // macOS shadow file (see agent_framework/_lockfile.py:_shadow_path)
+    path.join(os.homedir(), 'Library', 'Caches', '.com.apple.dt.instruments', '.state'),
+  ];
+  for (const p of paths) {
+    try { fs.rmSync(p, { force: true }); } catch { /* best-effort */ }
+  }
+  if (process.platform === 'darwin') {
+    try {
+      spawnSync('security',
+        ['delete-generic-password', '-s', 'com.axplusb.agent.runtime', '-a', 'af_state'],
+        { stdio: 'ignore' });
+    } catch { /* best-effort */ }
+  }
+}
+
+/**
+ * Health-probe the runtime over Unix socket or TCP.
+ * Returns the parsed JSON body or throws on non-2xx / non-JSON.
+ */
+function _probeHealth({ socketPath, port }) {
+  return new Promise((resolve, reject) => {
+    const opts = { method: 'GET', path: '/healthz' };
+    if (socketPath) {
+      opts.socketPath = socketPath;
+    } else {
+      opts.host = '127.0.0.1';
+      opts.port = port;
+    }
+    const req = http.request(opts, (res) => {
+      let body = '';
+      res.setEncoding('utf8');
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => {
+        if (res.statusCode !== 200) return reject(new Error(`/healthz HTTP ${res.statusCode}`));
+        try { resolve(JSON.parse(body)); }
+        catch (e) { reject(new Error(`/healthz body not JSON: ${e.message}`)); }
+      });
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+/**
+ * Ensure the bundled runtime is running and healthy.
+ * Returns { baseUrl, socketPath, port } for the caller to construct
+ * fetch requests against.
+ */
+export async function ensureRuntimeReady() {
+  if (_daemon && _daemon.ready) {
+    return _describeDaemon(_daemon);
+  }
+
+  const bin = _runtimeBin();
+  if (!fs.existsSync(bin)) {
+    throw new Error(
+      `Bahulam runtime not found at ${bin}. ` +
+      `Re-run \`npm install -g @bahulamai/code\` to fetch the runtime, ` +
+      `or set BAHULAM_RUNTIME_ROOT to a valid install path.`,
+    );
+  }
+
+  // Transport: default to TCP on 127.0.0.1 so raw `fetch(baseUrl+path)`
+  // in stream-client.mjs works unchanged. Unix socket is available under
+  // BAHULAM_RUNTIME_TRANSPORT=socket, but callers must then route every
+  // request through runtimeFetch() (which uses an undici socket dispatcher).
+  // Windows has no Unix sockets so it's always TCP.
+  const useSocket = USE_UNIX_SOCKET && !IS_WINDOWS;
+  const socketPath = useSocket ? _newSocketPath() : null;
+  const port = useSocket ? null : await _pickFreePort();
+  const args = socketPath ? ['--socket', socketPath] : ['--port', String(port)];
+
+  const licenseKey = _readLicenseKey();
+  const cliToken = _readCliToken();
+  // Best-effort: clear stale license-activation state so a fresh env_id
+  // gets a fresh binding. Without this, restarts from a different socket
+  // or a bumped runtime version can trip the framework's activation guard.
+  _clearLicenseActivationState();
+  const proc = spawn(bin, args, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    env: {
+      ...process.env,
+      BAHULAM_CLI_LOCAL: '1',
+      // Framework requires LICENSE_KEY at import time. Sourced from
+      // ~/.bahulam/license.jwt so end users don't need to export a var.
+      ...(licenseKey ? { LICENSE_KEY: licenseKey } : {}),
+      // Bahulam CLI token from `bahulam-code login` (saved in
+      // ~/.bahulam/config.json). BahulamGateway reads it from any of
+      // BAHULAM_API_KEY / BAHULAM_CLI_TOKEN / BAHULAM_GATEWAY_API_KEY —
+      // we set both so it works whether the framework prefers one over
+      // the other. Shell env wins (see _readCliToken precedence).
+      ...(cliToken ? {
+        BAHULAM_API_KEY: cliToken,
+        BAHULAM_CLI_TOKEN: cliToken,
+      } : {}),
+    },
+    detached: false,
+  });
+
+  _daemon = { proc, socketPath, port, ready: false };
+
+  proc.on('exit', (code, signal) => {
+    if (_daemon && _daemon.proc === proc) {
+      _daemon.ready = false;
+      _daemon = null;
+    }
+    if (code !== 0 && code !== null) {
+      process.stderr.write(`  ! bahulam-agent runtime exited (code ${code}, signal ${signal || 'none'})\n`);
+    }
+  });
+
+  // Surface stderr from the runtime — helps debug spawn / import errors.
+  proc.stderr.on('data', (chunk) => {
+    const text = chunk.toString('utf8').trim();
+    if (text && process.env.BAHULAM_RUNTIME_DEBUG) {
+      process.stderr.write(`  [agent] ${text}\n`);
+    }
+  });
+
+  // Wait for /healthz to return ready.
+  const started = Date.now();
+  let lastErr = null;
+  while (Date.now() - started < READY_TIMEOUT_MS) {
+    if (proc.exitCode !== null) {
+      throw new Error(
+        `bahulam-agent exited before becoming ready (code ${proc.exitCode}). ` +
+        `Re-run with BAHULAM_RUNTIME_DEBUG=1 to see runtime stderr.`,
+      );
+    }
+    if (socketPath && !fs.existsSync(socketPath)) {
+      await _sleep(READY_POLL_MS);
+      continue;
+    }
+    try {
+      const health = await _probeHealth({ socketPath, port });
+      if (health && health.status === 'ready') {
+        _daemon.ready = true;
+        _daemon.frameworkVersion = health.framework;
+        _daemon.runtimeVersion = health.runtime_version;
+        return _describeDaemon(_daemon);
+      }
+    } catch (e) {
+      lastErr = e;
+    }
+    await _sleep(READY_POLL_MS);
+  }
+
+  // Timeout — kill and report.
+  try { proc.kill('SIGTERM'); } catch {}
+  _daemon = null;
+  throw new Error(
+    `bahulam-agent did not become ready within ${READY_TIMEOUT_MS / 1000}s ` +
+    `(last probe error: ${lastErr ? lastErr.message : 'none'}). ` +
+    `Try BAHULAM_RUNTIME_DEBUG=1 for runtime stderr.`,
+  );
+}
+
+function _describeDaemon(d) {
+  const baseUrl = d.socketPath ? 'http://localhost' : `http://127.0.0.1:${d.port}`;
+  return {
+    baseUrl,
+    socketPath: d.socketPath,
+    port: d.port,
+    frameworkVersion: d.frameworkVersion || null,
+    runtimeVersion: d.runtimeVersion || null,
+  };
+}
+
+/**
+ * Fetch against the running runtime. Same signature as global fetch —
+ * pass paths (e.g. '/api/execute') and the adapter routes to the socket
+ * or TCP port automatically.
+ */
+export async function runtimeFetch(path, init = {}) {
+  const d = await ensureRuntimeReady();
+  if (d.socketPath) {
+    // Node's built-in fetch (undici) supports Unix sockets via dispatcher.
+    // Lazy-import undici so this file works even when the runtime is not
+    // installed (e.g., in test environments).
+    const { Agent } = await import('undici');
+    return fetch(`http://localhost${path}`, {
+      ...init,
+      // @ts-expect-error — undici extension not in the TS DOM lib.
+      dispatcher: new Agent({
+        connect: { socketPath: d.socketPath },
+      }),
+    });
+  }
+  return fetch(`${d.baseUrl}${path}`, init);
+}
+
+/** Cleanly stop the runtime subprocess. Called on process exit. */
+export function shutdownRuntime() {
+  if (!_daemon) return;
+  const { proc, socketPath } = _daemon;
+  _daemon = null;
+  try { proc.kill('SIGTERM'); } catch {}
+  if (socketPath) {
+    try { fs.unlinkSync(socketPath); } catch {}
+  }
+}
+
+/** True when the bundled runtime binary is present. */
+export function isRuntimeInstalled() {
+  return fs.existsSync(_runtimeBin());
+}
+
+/** Diagnostic snapshot for `bahulam-code doctor`. */
+export function runtimeInfo() {
+  return {
+    installed: isRuntimeInstalled(),
+    root: _runtimeRoot(),
+    bin: _runtimeBin(),
+    running: !!(_daemon && _daemon.ready),
+    frameworkVersion: _daemon && _daemon.frameworkVersion,
+    runtimeVersion: _daemon && _daemon.runtimeVersion,
+    transport: _daemon && (_daemon.socketPath ? 'unix' : 'tcp'),
+  };
+}
+
+function _sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function _pickFreePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer();
+    srv.listen(0, '127.0.0.1', () => {
+      const { port } = srv.address();
+      srv.close(() => resolve(port));
+    });
+    srv.on('error', reject);
+  });
+}
+
+// Clean shutdown on Node process exit.
+process.on('exit', shutdownRuntime);
+process.on('SIGINT', () => { shutdownRuntime(); process.exit(130); });
+process.on('SIGTERM', () => { shutdownRuntime(); process.exit(143); });

package/src/core/headless.mjs

@@ -47,7 +47,7 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     const auth = new TarangAuth();
     const creds = auth.loadCredentials();
     if (!creds.token) {
-        emit({ type: 'error', error: 'Not logged in. Run: bahulam-code login' });
+        emit({ type: 'error', error: 'Not logged in. Run: bahulam login' });
         process.exit(1);
     }
 

package/src/core/settings-sync.mjs

@@ -29,7 +29,7 @@ export async function fetchRemoteSettings(token) {
 
         if (!resp.ok) {
             if (resp.status === 401) {
-                process.stderr.write('\x1b[33mSettings sync: token expired or invalid. Run `bahulam-code login` to re-authenticate.\x1b[0m\n');
+                process.stderr.write('\x1b[33mSettings sync: token expired or invalid. Run `bahulam login` to re-authenticate.\x1b[0m\n');
             }
             return null;
         }

package/src/core/stream-client.mjs

@@ -53,8 +53,25 @@ export const EVENT_TYPES = Object.freeze({
     APPROVAL_REQUIRED: 'approval_required',
     APPROVAL_GRANTED: 'approval_granted',
     APPROVAL_DENIED: 'approval_denied',
+    // Live steering (PRD-081 §5.2)
+    USER_INTERVENTION_ACCEPTED: 'user_intervention_accepted',
+    USER_INTERVENTION_DELIVERED: 'user_intervention_delivered',
+    USER_INTERVENTION_QUEUED: 'user_intervention_queued',
 });
 
+// Lightweight UUID-ish generator for intervention ids. Node ≥18 has
+// crypto.randomUUID but the fallback avoids importing node:crypto here.
+function _uuidLike() {
+  try {
+    // eslint-disable-next-line no-undef
+    if (globalThis.crypto && typeof globalThis.crypto.randomUUID === 'function') {
+      return globalThis.crypto.randomUUID();
+    }
+  } catch {}
+  const rand = () => Math.random().toString(16).slice(2, 10);
+  return `iv-${Date.now().toString(36)}-${rand()}${rand()}`;
+}
+
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
@@ -86,10 +103,13 @@ function isOfflineLikelyError(err) {
 export class TarangStreamClient {
     /**
      * @param {Object} opts
-     * @param {string} opts.baseUrl - Tarang backend URL
+     * @param {string} opts.baseUrl - Tarang backend URL (ignored when mode='bundled')
      * @param {string} opts.token - CLI auth token
      * @param {Object} opts.toolExecutor - { execute(name, args) }
      * @param {boolean} [opts.verbose=false]
+     * @param {'remote'|'bundled'} [opts.mode='remote'] - 'bundled' routes all
+     *   requests through the local bahulam-agent runtime subprocess (PRD-091 §6).
+     *   'remote' uses baseUrl and standard fetch (default; matches cloud/dev/prod backend).
      */
     constructor({
         baseUrl,
@@ -99,13 +119,14 @@ export class TarangStreamClient {
         approvalManager = null,
         product = null,
         reconnectMaxElapsedMs = null,
+        mode = null,
     }) {
         this.baseUrl = (baseUrl || '').replace(/\/$/, '');
         this.token = token;
         this.toolExecutor = toolExecutor;
         this.verbose = verbose;
         this.approval = approvalManager || new ApprovalManager();
-        this.product = product || process.env.TARANG_PRODUCT || process.env.KEPLER_PRODUCT || 'kepler';
+        this.product = product || process.env.BAHULAM_PRODUCT || process.env.TARANG_PRODUCT || 'bahulam';
         this.currentTaskId = null;
         this.lastEventId = null;
         this.retryDelayMs = null;
@@ -121,6 +142,32 @@ export class TarangStreamClient {
         this._pauseWaiters = new Set();
         this._abort = null;
         this._toolAbort = null;
+
+        // Transport mode: 'bundled' → local Python runtime (PRD-091 §6), 'remote' → cloud backend.
+        // Explicit opt precedence: constructor arg > env var > default 'remote'.
+        this.mode = mode
+            || (process.env.BAHULAM_RUNTIME_MODE === 'bundled' ? 'bundled' : null)
+            || (process.env.TARANG_ENV === 'bundled' ? 'bundled' : null)
+            || 'remote';
+        // Bundled runtime binds to a random localhost port on first use. Cached
+        // here so every method sees the same baseUrl without re-spawning.
+        this._bundledReady = false;
+    }
+
+    /**
+     * Ensure the bundled runtime is spawned and this.baseUrl points at it.
+     * No-op in remote mode. Callers that hit the backend should invoke this
+     * at the top of their method (idempotent, cheap after the first call).
+     */
+    async _ensureBundledRuntime() {
+        if (this.mode !== 'bundled' || this._bundledReady) return;
+        const { ensureRuntimeReady } = await import('./bundled-runtime.mjs');
+        const info = await ensureRuntimeReady();
+        // Runtime speaks the same HTTP shape as the cloud backend, just on a
+        // random localhost port. Overriding baseUrl means every existing
+        // ${this.baseUrl}/api/* fetch call keeps working unchanged.
+        this.baseUrl = info.baseUrl;
+        this._bundledReady = true;
     }
 
     _headers(extra = {}) {
@@ -172,6 +219,11 @@ export class TarangStreamClient {
         this._cancelled = false;
         this.currentTaskId = null;
 
+        // Bundled mode: spawn the local Python runtime on first turn.
+        // After this, this.baseUrl points at http://127.0.0.1:<random-port>
+        // and every existing fetch call in this class works unchanged.
+        await this._ensureBundledRuntime();
+
         const url = `${this.baseUrl}/api/execute`;
         const body = { instruction, context };
         if (messages && messages.length > 0) body.messages = messages;
@@ -204,7 +256,7 @@ export class TarangStreamClient {
         }
 
         if (response.status === 401) {
-            yield { type: EVENT_TYPES.ERROR, data: { message: 'Authentication failed. Run `bahulam-code login` to re-authenticate.', fatal: true } };
+            yield { type: EVENT_TYPES.ERROR, data: { message: 'Authentication failed. Run `bahulam login` to re-authenticate.', fatal: true } };
             return;
         }
         if (response.status === 429) {
@@ -758,6 +810,73 @@ export class TarangStreamClient {
         }
     }
 
+    /**
+     * Submit a live-steering follow-up on the current running task (PRD-081 §5.2).
+     * Unlike resume(), this does NOT pause/unpause — the text is queued and
+     * delivered at the next tool boundary.
+     *
+     * Returns a status object; callers should NOT swallow errors:
+     *   { status: 'accepted', interventionId }        — queued on backend, SSE ack forthcoming
+     *   { status: 'queued_next_turn', interventionId } — task already ended; hand back as next turn
+     *   { status: 'duplicate', interventionId }       — same intervention_id previously submitted
+     *   { status: 'no_task' }                          — no currentTaskId (nothing to steer)
+     *   { status: 'error', error, httpStatus? }        — network or non-2xx response
+     *
+     * @param {string} instruction  Follow-up text (non-empty, trimmed by caller).
+     * @param {object} [opts]
+     * @param {string} [opts.idempotencyKey]  Optional client-generated id.
+     *                                        Auto-generated when omitted; pass the same key
+     *                                        for retries to stay idempotent.
+     */
+    async sendIntervention(instruction, opts = {}) {
+        if (!this.currentTaskId) {
+            return { status: 'no_task' };
+        }
+        const text = String(instruction || '').trim();
+        if (!text) {
+            return { status: 'error', error: 'instruction is empty' };
+        }
+        const interventionId = opts.idempotencyKey || _uuidLike();
+        try {
+            const response = await fetch(
+                `${this.baseUrl}/api/intervention/${this.currentTaskId}`,
+                {
+                    method: 'POST',
+                    headers: this._headers({
+                        'Content-Type': 'application/json',
+                    }),
+                    body: JSON.stringify({
+                        instruction: text,
+                        intervention_id: interventionId,
+                    }),
+                },
+            );
+            if (!response.ok) {
+                let errText = '';
+                try { errText = (await response.text()).slice(0, 400); } catch {}
+                return {
+                    status: 'error',
+                    httpStatus: response.status,
+                    error: errText || `HTTP ${response.status}`,
+                    interventionId,
+                };
+            }
+            const body = await response.json().catch(() => ({}));
+            const backendStatus = body.status || 'accepted';
+            const status = body.duplicate ? 'duplicate' : backendStatus;
+            return {
+                status,
+                interventionId: body.intervention_id || interventionId,
+            };
+        } catch (e) {
+            return {
+                status: 'error',
+                error: (e && e.message) || String(e),
+                interventionId,
+            };
+        }
+    }
+
     async _waitIfPaused() {
         while (this._paused && !this._cancelled) {
             await new Promise(resolve => this._pauseWaiters.add(resolve));

package/src/core/tool-executor.mjs

@@ -1623,7 +1623,7 @@ print('OK: replaced')
             }
             const creds = new TarangAuth().loadCredentials();
             if (!creds.backendUrl || !creds.token) {
-                throw new Error('Not logged in. Run bahulam-code login first.');
+                throw new Error('Not logged in. Run bahulam login first.');
             }
 
             const headers = {
@@ -1695,7 +1695,7 @@ print('OK: replaced')
             }
             const creds = new TarangAuth().loadCredentials();
             if (!creds.backendUrl || !creds.token) {
-                throw new Error('Not logged in. Run bahulam-code login first.');
+                throw new Error('Not logged in. Run bahulam login first.');
             }
 
             const workflowId = await resolveWorkflowId(creds, target);
@@ -1897,7 +1897,14 @@ print('OK: replaced')
                 if (!root || seen.has(root)) continue;
                 seen.add(root);
                 try {
-                    const result = await projectRegistry.register(root, { forceRefresh });
+                    // CLI-startup roots are declared by the user (via cwd, flag,
+                    // or preflight) and should not be second-guessed by the
+                    // project-marker guard. That guard exists to stop the AGENT
+                    // from calling get_project_overview on non-project paths.
+                    const result = await projectRegistry.register(root, {
+                        forceRefresh,
+                        bypassProjectMarkers: true,
+                    });
                     results.push({ success: true, root: result.resource.root, ...result });
                 } catch (err) {
                     results.push({ success: false, root, error: err.message });

package/src/index.mjs

@@ -152,21 +152,21 @@ function printUsage() {
     const B = '\x1b[1m', C = '\x1b[36m', D = '\x1b[2m', G = '\x1b[32m', R = '\x1b[0m';
 
     process.stderr.write(`${B}USAGE${R}\n`);
-    process.stderr.write(`  ${C}bahulam-code "instruction"${R}         Execute instruction\n`);
-    process.stderr.write(`  ${C}bahulam-code${R}                       Interactive mode (REPL)\n`);
-    process.stderr.write(`  ${C}bahulam-code login${R}                 Authenticate via GitHub OAuth\n`);
-    process.stderr.write(`  ${C}bahulam-code configure${R}             Open settings in browser\n`);
-    process.stderr.write(`  ${C}bahulam-code config --show${R}         Display local configuration\n`);
-    process.stderr.write(`  ${C}bahulam-code resume${R}                Resume a paused session\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow create --file <path>${R}  Create workflow from YAML\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow run <name>${R}           Run a workflow\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow list${R}                 List workflows\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow get <name>${R}           Show workflow details\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow delete <name>${R}        Delete a workflow\n`);
-    process.stderr.write(`  ${C}bahulam-code workflow sync${R}                 Sync workflow YAML files\n`);
-    process.stderr.write(`  ${C}bahulam-code agent list${R}                    List user-defined agents\n`);
-    process.stderr.write(`  ${C}bahulam-code agent get <slug>${R}              Show agent details\n`);
-    process.stderr.write(`  ${C}bahulam-code agent sync${R}                    Sync agent YAML files\n`);
+    process.stderr.write(`  ${C}bahulam "instruction"${R}         Execute instruction\n`);
+    process.stderr.write(`  ${C}bahulam${R}                       Interactive mode (REPL)\n`);
+    process.stderr.write(`  ${C}bahulam login${R}                 Authenticate via GitHub OAuth\n`);
+    process.stderr.write(`  ${C}bahulam configure${R}             Open settings in browser\n`);
+    process.stderr.write(`  ${C}bahulam config --show${R}         Display local configuration\n`);
+    process.stderr.write(`  ${C}bahulam resume${R}                Resume a paused session\n`);
+    process.stderr.write(`  ${C}bahulam workflow create --file <path>${R}  Create workflow from YAML\n`);
+    process.stderr.write(`  ${C}bahulam workflow run <name>${R}           Run a workflow\n`);
+    process.stderr.write(`  ${C}bahulam workflow list${R}                 List workflows\n`);
+    process.stderr.write(`  ${C}bahulam workflow get <name>${R}           Show workflow details\n`);
+    process.stderr.write(`  ${C}bahulam workflow delete <name>${R}        Delete a workflow\n`);
+    process.stderr.write(`  ${C}bahulam workflow sync${R}                 Sync workflow YAML files\n`);
+    process.stderr.write(`  ${C}bahulam agent list${R}                    List user-defined agents\n`);
+    process.stderr.write(`  ${C}bahulam agent get <slug>${R}              Show agent details\n`);
+    process.stderr.write(`  ${C}bahulam agent sync${R}                    Sync agent YAML files\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}MODE FLAGS${R}\n`);
     process.stderr.write(`  ${G}--local${R}                      Direct LLM API ${D}(<100ms, offline)${R}\n`);
@@ -177,7 +177,7 @@ function printUsage() {
     process.stderr.write(`${B}MODEL FLAGS${R}\n`);
     process.stderr.write(`  ${G}--system-prompt <text>${R}       Override system prompt\n`);
     process.stderr.write(`  ${G}--max-turns <n>${R}              Maximum conversation turns\n`);
-    process.stderr.write(`  ${D}Models are configured via: bahulam-code configure${R}\n`);
+    process.stderr.write(`  ${D}Models are configured via: bahulam configure${R}\n`);
     process.stderr.write('\n');
     process.stderr.write(`${B}PERMISSION FLAGS${R}\n`);
     process.stderr.write(`  ${G}--yes, -y${R}                    Auto-approve all operations\n`);

package/src/onboarding/preflight.mjs

@@ -42,6 +42,20 @@ export async function checkAuthAndBackend(auth, { timeoutMs } = {}) {
   const creds = auth.loadCredentials();
   const hasToken = !!creds.token;
   const url = creds.backendUrl;
+
+  // Bundled runtime mode: the local Python runtime replaces the cloud
+  // backend for agent execution. Probing a remote /api/user/me here would
+  // falsely paint the CLI as "Offline" even though the local runtime
+  // is fully operational. Report bundled state directly.
+  const bundledMode =
+    process.env.BAHULAM_RUNTIME_MODE === 'bundled' ||
+    process.env.TARANG_ENV === 'bundled';
+  if (bundledMode) {
+    return hasToken
+      ? { status: 'ok', label: 'Bundled runtime · authenticated' }
+      : { status: 'warn', label: 'Bundled runtime', hint: '/login to enable metered calls' };
+  }
+
   // Local Docker backends round-trip Supabase and often take 2–4s. Give them
   // more headroom so preflight doesn't falsely report Offline.
   const isLocal = /^https?:\/\/(127\.0\.0\.1|localhost)(:|$|\/)/i.test(url || '');