@bahulam/code 0.1.11 → 0.1.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.11",
+  "version": "0.1.12",
   "description": "Bahulam Code — abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {

package/src/auth/tarang-auth.mjs

@@ -0,0 +1,313 @@
+/**
+ * Bahulam Code Authentication — GitHub OAuth + config management.
+ * Reads/writes ~/.bahulam/config.json (fallback: ~/.kepler/config.json for
+ * legacy installs — see src/core/paths.mjs for the resolver).
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as http from 'node:http';
+import { getLoginSuccessHTML } from '../ui/banner.mjs';
+import { resolveBackendUrl } from '../core/backend-url.mjs';
+import { bahulamHome } from '../core/paths.mjs';
+
+// Note: computed via a function (not a constant) so that BAHULAM_HOME /
+// KEPLER_HOME env-var swaps mid-process still work.
+function configDir() { return bahulamHome(); }
+function configPath() { return path.join(configDir(), 'config.json'); }
+
+// Legacy exports kept for backwards compat with any tests/scripts that
+// still import CONFIG_DIR / CONFIG_PATH by name.
+const CONFIG_DIR = configDir();
+const CONFIG_PATH = configPath();
+
+let _tokenEnvNoticeShown = false;
+function readTokenFromEnv() {
+    if (process.env.B0_TOKEN) return process.env.B0_TOKEN;
+    if (process.env.KEPLER_TOKEN) {
+        if (!_tokenEnvNoticeShown && process.env.B0_QUIET_MIGRATION !== '1') {
+            _tokenEnvNoticeShown = true;
+            try {
+                process.stderr.write(
+                    '  \x1b[2mnote: KEPLER_TOKEN is deprecated; set B0_TOKEN instead.\x1b[0m\n'
+                );
+            } catch {}
+        }
+        return process.env.KEPLER_TOKEN;
+    }
+    return null;
+}
+
+export class TarangAuth {
+    constructor() {
+        this._config = null;
+    }
+
+    /** Ensure ~/.bahulam/ (or legacy ~/.kepler/) exists with secure permissions. */
+    _ensureConfigDir() {
+        const dir = configDir();
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+        }
+    }
+
+    /** Load credentials and settings from config.json. */
+    loadCredentials() {
+        const cfgPath = configPath();
+        try {
+            if (fs.existsSync(cfgPath)) {
+                const raw = fs.readFileSync(cfgPath, 'utf-8');
+                this._config = JSON.parse(raw);
+            } else {
+                this._config = {};
+            }
+        } catch {
+            this._config = {};
+        }
+        return {
+            token: readTokenFromEnv() || this._config.token || null,
+            openRouterKey: this._config.openrouter_key || process.env.OPENROUTER_API_KEY || null,
+            anthropicKey: this._config.anthropic_api_key || process.env.ANTHROPIC_API_KEY || null,
+            openaiKey: this._config.openai_api_key || process.env.OPENAI_API_KEY || null,
+            googleKey: this._config.google_api_key || process.env.GOOGLE_API_KEY || null,
+            backendUrl: resolveBackendUrl(),
+            mode: this._config.mode || 'auto',
+            gatewayType: this._config.gateway_type || 'openrouter',
+            models: this._config.models || {},
+            configuredProviders: this._config.configured_providers || [],
+            gatewayConfig: this._config.gateway_config || {},
+            // PRD-076 W7: persisted /model picks. `modelConfig` mirrors the
+            // Python-side key read_local_model_config() looks for; keep the
+            // snake_case JSON key so the runtime picks it up unchanged.
+            modelConfig: this._config.model_config || {},
+            modelMode: this._config.model_mode || null,
+            routePreference: this._config.route_preference || null,
+        };
+    }
+
+    /** Get the raw config object. */
+    getRawConfig() {
+        if (!this._config) this.loadCredentials();
+        return this._config || {};
+    }
+
+    /** Clear credentials — remove token and keys from config. */
+    logout() {
+        try {
+            const cfgPath = configPath();
+            if (fs.existsSync(cfgPath)) {
+                fs.unlinkSync(cfgPath);
+            }
+            this._config = null;
+            return true;
+        } catch {
+            return false;
+        }
+    }
+
+    /** Save credentials atomically (temp-file + rename). */
+    saveCredentials(updates) {
+        this._ensureConfigDir();
+        const current = this._config || {};
+        const merged = { ...current, ...updates };
+        const cfgPath = configPath();
+        const tmpPath = `${cfgPath}.tmp.${process.pid}`;
+        fs.writeFileSync(tmpPath, JSON.stringify(merged, null, 2), { mode: 0o600 });
+        fs.renameSync(tmpPath, cfgPath);
+        this._config = merged;
+    }
+
+    /** Check if user has a valid auth token. */
+    isAuthenticated() {
+        const creds = this.loadCredentials();
+        return !!creds.token;
+    }
+
+    /** Check if OpenRouter key is configured. */
+    hasOpenRouterKey() {
+        const creds = this.loadCredentials();
+        return !!creds.openRouterKey;
+    }
+
+    /** Save an API key by provider name. */
+    saveProviderKey(provider, key) {
+        const keyMap = {
+            openrouter: 'openrouter_key',
+            anthropic: 'anthropic_api_key',
+            openai: 'openai_api_key',
+            googleai: 'google_api_key',
+            azureopenai: 'azure_api_key',
+            bedrock: 'aws_access_key',
+            databricks: 'databricks_token',
+        };
+        const field = keyMap[provider];
+        if (!field) throw new Error(`Unknown provider: ${provider}`);
+        this.saveCredentials({ [field]: key });
+    }
+
+    /** Save OpenRouter API key. */
+    saveOpenRouterKey(key) {
+        this.saveProviderKey('openrouter', key);
+    }
+
+    /** Save Anthropic API key. */
+    saveAnthropicKey(key) {
+        this.saveProviderKey('anthropic', key);
+    }
+
+    /** Save OpenAI API key. */
+    saveOpenAIKey(key) {
+        this.saveProviderKey('openai', key);
+    }
+
+    /** Save Google AI API key. */
+    saveGoogleKey(key) {
+        this.saveProviderKey('googleai', key);
+    }
+
+    /** Sync settings from web backend and save locally. */
+    async syncSettings() {
+        const { fetchRemoteSettings, mergeRemoteSettings } = await import('../core/settings-sync.mjs');
+        const creds = this.loadCredentials();
+        if (!creds.token) throw new Error('Not logged in. Run `bahulam-code login` first.');
+
+        const remote = await fetchRemoteSettings(creds.token);
+        if (!remote) throw new Error('Failed to fetch settings from server.');
+
+        const merged = mergeRemoteSettings(this.getRawConfig(), remote);
+        this.saveCredentials(merged);
+        return remote;
+    }
+
+    /** Set default mode. */
+    setMode(mode) {
+        const valid = ['local', 'remote', 'auto'];
+        if (!valid.includes(mode)) {
+            throw new Error(`Invalid mode: ${mode}. Must be one of: ${valid.join(', ')}`);
+        }
+        this.saveCredentials({ mode });
+    }
+
+    /** Display config (styled). */
+    printConfig() {
+        const creds = this.loadCredentials();
+        const GREEN = '\x1b[32m', RED = '\x1b[31m', DIM = '\x1b[2m', BOLD = '\x1b[1m', CYAN = '\x1b[36m', RESET = '\x1b[0m';
+        const check = `${GREEN}\u2713${RESET}`;
+        const cross = `${RED}\u2717${RESET}`;
+
+        const env = process.env.TARANG_ENV || process.env.NODE_ENV || 'production';
+
+        process.stderr.write(`\n${BOLD}Bahulam Code Configuration${RESET}\n`);
+        process.stderr.write(`${'─'.repeat(50)}\n`);
+        process.stderr.write(`  Auth:           ${creds.token ? `${check} logged in` : `${cross} not logged in ${DIM}(/login)${RESET}`}\n`);
+        process.stderr.write(`  Environment:    ${DIM}${env}${RESET}\n`);
+        process.stderr.write(`  Backend:        ${DIM}${creds.backendUrl}${RESET}\n`);
+        process.stderr.write(`  Mode:           ${DIM}${creds.mode || 'auto'}${RESET}\n`);
+        process.stderr.write(`  Gateway:        ${DIM}${creds.gatewayType}${RESET}\n`);
+
+        const models = creds.models || {};
+        const planningModel = models.planning || models.orchestrator;
+        if (planningModel || models.reasoning || models.local) {
+            process.stderr.write(`\n${BOLD}  Models${RESET}\n`);
+            if (planningModel)       process.stderr.write(`  Planning:       ${DIM}${planningModel}${RESET}\n`);
+            if (models.reasoning)    process.stderr.write(`  Coding:         ${DIM}${models.reasoning}${RESET}\n`);
+            if (models.local)        process.stderr.write(`  Local:          ${DIM}${models.local}${RESET}\n`);
+        }
+
+        const providers = creds.configuredProviders || [];
+        if (providers.length > 0) {
+            process.stderr.write(`  Providers:      ${DIM}${providers.join(', ')}${RESET}\n`);
+        }
+
+        const raw = this.getRawConfig();
+        if (raw.last_synced_at) {
+            process.stderr.write(`  Last synced:    ${DIM}${new Date(raw.last_synced_at).toLocaleString()}${RESET}\n`);
+        }
+
+        process.stderr.write(`\n  ${DIM}Run ${RESET}${CYAN}bahulam-code sync${RESET}${DIM} to sync settings from web.${RESET}\n`);
+        process.stderr.write(`  ${DIM}Run ${RESET}${CYAN}bahulam-code configure${RESET}${DIM} to open settings in browser.${RESET}\n`);
+        process.stderr.write('\n');
+    }
+
+    /**
+     * Run login flow via web app.
+     *
+     * Flow:
+     *   1. CLI starts local HTTP server on random port
+     *   2. Opens browser to web /auth/cli?callback=http://127.0.0.1:{port}/callback
+     *   3. Web checks Supabase session (if none → GitHub OAuth → Supabase)
+     *   4. Web generates CLI token via /api/cli/token
+     *   5. Web redirects browser to CLI callback with token
+     *   6. CLI receives token, saves to ~/.bahulam/config.json
+     */
+    async login() {
+        const { resolveWebUrl } = await import('../core/backend-url.mjs');
+        const webUrl = resolveWebUrl();
+
+        return new Promise((resolve, reject) => {
+            const server = http.createServer(async (req, res) => {
+                const url = new URL(req.url, `http://localhost`);
+
+                // The web app redirects here with ?token=<cli_token>
+                const token = url.searchParams.get('token');
+
+                if (!token) {
+                    // Maybe an error or missing token
+                    const error = url.searchParams.get('error');
+                    if (error) {
+                        res.writeHead(200, { 'Content-Type': 'text/html' });
+                        res.end(`<html><body><h2>Login failed</h2><p>${error}</p></body></html>`);
+                        server.close();
+                        reject(new Error(error));
+                        return;
+                    }
+                    // Ignore other requests (favicon, etc.)
+                    res.writeHead(200);
+                    res.end('');
+                    return;
+                }
+
+                // Save the CLI token
+                this.saveCredentials({ token });
+
+                res.writeHead(200, { 'Content-Type': 'text/html' });
+                res.end(getLoginSuccessHTML());
+
+                server.close();
+                resolve(true);
+            });
+
+            server.listen(0, '127.0.0.1', () => {
+                const port = server.address().port;
+                const callbackUrl = `http://127.0.0.1:${port}/callback`;
+                const authUrl = `${webUrl}/auth/cli?callback=${encodeURIComponent(callbackUrl)}`;
+
+                process.stderr.write(`\n\x1b[36mOpening browser for login...\x1b[0m\n`);
+                process.stderr.write(`\x1b[2mIf browser doesn't open, visit:\x1b[0m\n  \x1b[4m${authUrl}\x1b[0m\n\n`);
+
+                // Open browser
+                const openCmd = process.platform === 'darwin' ? 'open' :
+                                process.platform === 'win32' ? 'start' : 'xdg-open';
+                import('node:child_process').then(({ exec }) => {
+                    exec(`${openCmd} "${authUrl}"`, () => {});
+                });
+            });
+
+            // Timeout after 120s
+            setTimeout(() => {
+                server.close();
+                reject(new Error('Login timed out after 120s'));
+            }, 120_000);
+        });
+    }
+
+    /**
+     * Ensure user is authenticated, prompt login if not.
+     */
+    async ensureAuth() {
+        if (!this.isAuthenticated()) {
+            process.stderr.write('\x1b[33mNot logged in.\x1b[0m Starting login flow...\n');
+            await this.login();
+        }
+    }
+}

package/src/commands/agent.mjs

@@ -1,5 +1,5 @@
 /**
- * Agent CLI Commands — list, get, sync user-defined agents.
+ * Agent CLI Commands — list, get, sync backend-published user-defined agents.
  *
  * Commands:
  *   bahulam-code agent list
@@ -47,9 +47,9 @@ export async function handleAgentCommand(args) {
 
 function printAgentUsage() {
     process.stderr.write(`${BOLD}AGENT COMMANDS${RESET}\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent list${RESET}                           List user-defined agents\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent get <slug>${RESET}                     Show agent details\n`);
-    process.stderr.write(`  ${CYAN}bahulam-code agent sync [--dir <path>]${RESET}            Sync agent YAML files\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent list${RESET}                           List backend-published agents\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent get <slug>${RESET}                     Show backend-published agent details\n`);
+    process.stderr.write(`  ${CYAN}bahulam-code agent sync [--dir <path>]${RESET}            Publish local agent YAML files for account/cloud reuse\n`);
     process.stderr.write('\n');
 }
 
@@ -110,11 +110,11 @@ async function handleList(args) {
 
     const agents = result.agents || [];
     if (agents.length === 0) {
-        process.stderr.write(`${DIM}No user-defined agents found.${RESET}\n`);
+        process.stderr.write(`${DIM}No backend-published agents found. Local .bahulam/agents files can still be delegated in their workspace.${RESET}\n`);
         process.exit(0);
     }
 
-    process.stderr.write(`${BOLD}User-defined Agents:${RESET}\n`);
+    process.stderr.write(`${BOLD}Backend-published Agents:${RESET}\n`);
     for (const a of agents) {
         const source = a.source === 'platform' ? `${DIM}(platform)${RESET}` : `${DIM}(user)${RESET}`;
         process.stderr.write(`  ${CYAN}${a.slug}${RESET}  ${a.name || a.slug} ${source}\n`);
@@ -184,7 +184,7 @@ async function handleSync(args) {
             agents: selected,
         });
         const synced = result.synced ?? selected.length;
-        process.stderr.write(`${GREEN}✓ Synced ${synced} agent${synced === 1 ? '' : 's'} to Supabase.${RESET}\n`);
+        process.stderr.write(`${GREEN}✓ Synced ${synced} agent${synced === 1 ? '' : 's'} to the backend for account/cloud reuse.${RESET}\n`);
         process.stdout.write(JSON.stringify({ synced, agents: result.agents || [] }, null, 2) + '\n');
     } catch (err) {
         process.stderr.write(`${RED}✗ Agent sync failed: ${err.message}${RESET}\n`);

package/src/config/cli-args.mjs

@@ -11,6 +11,8 @@
  * --max-turns          Maximum conversation turns
  * --allowedTools       Comma-separated allowed tools
  * --disallowedTools    Comma-separated denied tools
+ * --agent <slug>       Run a named agent (local deterministic graph)
+ * --workflow <name>    Run a named workflow (local deterministic graph)
  * --verbose, -v        Verbose output
  * --debug, -d          Debug mode
  * --version            Show version
@@ -34,6 +36,8 @@ export function parseArgs(args) {
         resumeSessionId: null,
         headless: false,
         skipPermissions: false,
+        agent: null,
+        workflow: null,
         vision: [],
         verbose: false,
         debug: false,
@@ -109,6 +113,14 @@ export function parseArgs(args) {
                 result.skipPermissions = true; // headless implies skip permissions
                 break;
 
+            case '--agent':
+                result.agent = args[++i];
+                break;
+
+            case '--workflow':
+                result.workflow = args[++i];
+                break;
+
             case '--cache-report':
                 // PRD-071 §1.5 — write a machine-readable cache summary to
                 // <path> at end of run. Consumed by benchmark/cache-check.sh.
@@ -184,6 +196,8 @@ Options:
   --disallowedTools <tools>  Comma-separated list of denied tools
   --resume, -r [sessionId]   Resume last session (or specific session)
   --continue                 Alias for --resume
+  --agent <slug>             Run a named agent as a deterministic local graph
+  --workflow <name>          Run a named workflow as a deterministic local graph
   --headless                 Non-interactive mode: auto-approve, JSONL output
   --cache-report <file>      Write prompt-cache summary JSON to <file> (headless only)
   --vision <image-path>      Attach image path in headless mode
@@ -197,6 +211,8 @@ Examples:
   occ                        Start interactive REPL
   occ -p "What is 2+2?"     Run prompt and exit
   occ -m claude-haiku-4-5    Use Haiku model
+  occ --agent explore -p "Map auth flow"  Run the explore agent headlessly
+  occ --workflow deploy -p "Deploy"       Run a workflow headlessly
   occ --debug -p "Fix bug"  Debug mode with prompt
 `.trim();
 }

package/src/core/background-tasks.mjs

@@ -0,0 +1,186 @@
+/**
+ * BackgroundTasks — the one registry for long-running processes the agent
+ * starts (docker build, npm run dev, test suites). Jobs get a run id,
+ * a per-job timeout with SIGTERM→SIGKILL escalation, output spooled to
+ * .bahulam/tmp/jobs/<id>.log (with a bounded in-memory tail), completion
+ * listeners for wake-on-finish delivery, and best-effort cleanup of the
+ * whole process group when the CLI exits.
+ */
+import { spawn } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+const KILL_ESCALATION_MS = 5000;
+const MAX_TAIL_BYTES = 64 * 1024;
+
+function stripAnsi(str) {
+  // eslint-disable-next-line no-control-regex
+  return String(str || '').replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+}
+
+class BackgroundTasks {
+  constructor() {
+    this.jobs = new Map();
+    this._seq = 0;
+    this._listeners = new Set();
+    this._exitHookInstalled = false;
+  }
+
+  onExit(listener) {
+    this._listeners.add(listener);
+    return () => this._listeners.delete(listener);
+  }
+
+  start({ command, cwd = process.cwd(), timeoutMs = DEFAULT_TIMEOUT_MS, name = '', on_complete = null }) {
+    this._installExitHook();
+    const id = `job-${++this._seq}-${Date.now().toString(36)}`;
+    const logDir = path.join(cwd, '.bahulam', 'tmp', 'jobs');
+    fs.mkdirSync(logDir, { recursive: true });
+    const logPath = path.join(logDir, `${id}.log`);
+    const logStream = fs.createWriteStream(logPath);
+
+    const proc = spawn('bash', ['-c', command], {
+      cwd,
+      env: { ...process.env },
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+
+    const job = {
+      id,
+      name: name || command.slice(0, 60),
+      command,
+      cwd,
+      pid: proc.pid,
+      status: 'running',
+      exit_code: null,
+      started_at: Date.now(),
+      ended_at: null,
+      log_path: logPath,
+      tail: '',
+      timed_out: false,
+      on_complete,
+      _proc: proc,
+      _done: null,
+    };
+
+    const appendTail = (chunk) => {
+      const next = job.tail + chunk.toString();
+      job.tail = next.length > MAX_TAIL_BYTES ? next.slice(next.length - MAX_TAIL_BYTES) : next;
+    };
+    proc.stdout.on('data', (d) => { logStream.write(d); appendTail(d); });
+    proc.stderr.on('data', (d) => { logStream.write(d); appendTail(d); });
+
+    let killTimer = null;
+    const timer = timeoutMs > 0 ? setTimeout(() => {
+      job.timed_out = true;
+      this._kill(job, 'SIGTERM');
+      killTimer = setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS);
+    }, timeoutMs) : null;
+    if (timer?.unref) timer.unref();
+
+    job._done = new Promise((resolve) => {
+      proc.on('close', (code) => {
+        clearTimeout(timer);
+        clearTimeout(killTimer);
+        job.exit_code = code;
+        job.ended_at = Date.now();
+        job.status = job.timed_out ? 'timeout'
+          : job.status === 'killed' ? 'killed'
+          : code === 0 ? 'completed' : 'failed';
+        job.tail = stripAnsi(job.tail);
+        logStream.end();
+        for (const listener of this._listeners) {
+          try { listener(this.describe(job.id)); } catch { /* listeners are best-effort */ }
+        }
+        resolve(this.describe(job.id));
+      });
+      proc.on('error', (err) => {
+        job.status = 'failed';
+        job.tail = `${job.tail}\n${err.message}`.trim();
+        job.ended_at = Date.now();
+        logStream.end();
+        resolve(this.describe(job.id));
+      });
+    });
+
+    proc.unref();
+    this.jobs.set(id, job);
+    return this.describe(id);
+  }
+
+  /** Await a job's completion; resolves with its final description. */
+  wait(id) {
+    const job = this.jobs.get(id);
+    if (!job) return Promise.resolve(null);
+    if (job.status !== 'running') return Promise.resolve(this.describe(id));
+    // Background jobs are unref'd so fire-and-forget tasks do not pin the CLI
+    // open. When a caller explicitly awaits wait(id), temporarily ref the
+    // process so fast commands still get their close event before Node decides
+    // the top-level await is unsettled.
+    try { job._proc?.ref?.(); } catch { /* best effort */ }
+    return job._done.finally(() => {
+      try { job._proc?.unref?.(); } catch { /* best effort */ }
+    });
+  }
+
+  describe(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    return {
+      id: job.id,
+      name: job.name,
+      command: job.command,
+      pid: job.pid,
+      status: job.status,
+      exit_code: job.exit_code,
+      duration_s: Math.round(((job.ended_at || Date.now()) - job.started_at) / 1000),
+      log_path: job.log_path,
+      tail: job.tail,
+      timed_out: job.timed_out,
+      on_complete: job.on_complete || null,
+    };
+  }
+
+  list() {
+    return [...this.jobs.keys()].map(id => {
+      const d = this.describe(id);
+      return { ...d, tail: undefined };
+    });
+  }
+
+  kill(id) {
+    const job = this.jobs.get(id);
+    if (!job) return null;
+    if (job.status === 'running') {
+      job.status = 'killed';
+      this._kill(job, 'SIGTERM');
+      setTimeout(() => this._kill(job, 'SIGKILL'), KILL_ESCALATION_MS)?.unref?.();
+    }
+    return this.describe(id);
+  }
+
+  _kill(job, signal) {
+    if (!job?._proc?.pid) return;
+    try {
+      if (process.platform !== 'win32') {
+        process.kill(-job._proc.pid, signal);
+        return;
+      }
+    } catch { /* fall through */ }
+    try { job._proc.kill(signal); } catch { /* already exited */ }
+  }
+
+  _installExitHook() {
+    if (this._exitHookInstalled) return;
+    this._exitHookInstalled = true;
+    process.on('exit', () => {
+      for (const job of this.jobs.values()) {
+        if (job.status === 'running') this._kill(job, 'SIGKILL');
+      }
+    });
+  }
+}
+
+export const backgroundTasks = new BackgroundTasks();

package/src/core/headless.mjs

@@ -47,7 +47,7 @@ import {
  * @param {number} [opts.maxCost] - abort if cost exceeds this USD amount
  * @param {boolean} [opts.verbose] - show progress on stderr
  */
-export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false, vision = [] }) {
+export async function runHeadless({ instruction, model, timeout = 300, maxCost, verbose = false, cacheReport = null, local = false, vision = [], agent = null, workflow = null }) {
     const startTime = Date.now();
 
     const log = (msg) => {
@@ -61,12 +61,63 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     // ── Auth ──
     const auth = new BahulamAuth();
     const creds = auth.loadCredentials();
-    if (!creds.token) {
+    const graphTarget = agent || workflow;
+    const anthKey = process.env.ANTHROPIC_API_KEY || creds.anthropicKey;
+    const orKey = process.env.OPENROUTER_API_KEY || creds.openRouterKey;
+    // Graph runs execute locally and only need a model key; everything
+    // else still requires login (the backend runs the agent loop).
+    if (!creds.token && !(graphTarget && (anthKey || orKey))) {
         emit({ type: 'error', error: 'Not logged in. Run: bahulam login' });
         process.exit(1);
     }
 
-    // Scan plugins so client_tools and client_agents are sent to the backend.
+    // ── Deterministic graph target: --agent <slug> / --workflow <name> ──
+    if (graphTarget) {
+        const { dispatch } = await import('../orchestration/dispatch.mjs');
+        const { listLocalWorkflows } = await import('../agents/workflow_scaffold.mjs');
+        const pluginRegistry = new PluginRegistry().scan();
+        const toolExecutor = createToolExecutor({ pluginRegistry });
+        const timer = setTimeout(() => {
+            emit({ type: 'timeout', duration_s: timeout });
+            process.exit(2);
+        }, timeout * 1000);
+
+        const outcome = await dispatch({
+            type: 'invoke',
+            source: 'cli:headless',
+            target: agent ? { kind: 'agent', slug: agent } : { kind: 'workflow', slug: workflow },
+            params: { instruction: instruction || '' },
+            channel: null,
+            substrate: 'direct',
+        }, {
+            toolExecutor,
+            listRunnables: () => toolExecutor.listRunnables(),
+            listLocalWorkflows: () => listLocalWorkflows(process.cwd()),
+            renderEvent: (event) => emit({ type: event.type, ...event.data }),
+            credentials: { apiKey: anthKey, openRouterKey: orKey },
+            defaultModel: model || null,
+            cwd: process.cwd(),
+        });
+
+        clearTimeout(timer);
+        if (!outcome.dispatched) {
+            emit({ type: 'error', error: outcome.reason });
+            process.exit(1);
+        }
+        const result = outcome.result || {};
+        emit({
+            type: 'result',
+            status: result.status || (result.success === false ? 'failed' : 'completed'),
+            channel: outcome.channel,
+            output: result.output || '',
+            node_results: result.node_results || undefined,
+            duration_s: Math.round((Date.now() - startTime) / 1000),
+        });
+        process.exit(result.status === 'failed' || result.success === false ? 1 : 0);
+    }
+
+    // Scan plugins so client_agents and agent-scoped plugin tool schemas
+    // are sent to the backend.
     const pluginRegistry = new PluginRegistry().scan();
 
     // Projects are registered and indexed only when the agent requests an overview.