@phuetz/code-buddy 1.0.0-rc.8 → 1.0.0

package/README.md

@@ -241,6 +241,7 @@ From source, Cowork requires Node.js `>=22` in `cowork/`; the root CLI still sup
 | [Channels](docs/channels.md) | 20+ messaging channels, DM pairing, send policy |
 | [Context Engine](docs/context-engine.md) | Compression, tool output masking, JIT context, pre-compaction flush |
 | [Infrastructure](docs/infrastructure.md) | HTTP server, WebSocket gateway, daemon, cron, deploy, plugins |
+| [Deployment](docs/deployment.md) | Production deployment — systemd, Docker, Kubernetes, reverse proxy, env vars, upgrades |
 | [PdfCommander MCP Integration](docs/mcp-pdfcommander-integration.md) | Register the PdfCommander headless MCP server in `mcp.json`, verify with `buddy mcp test`, drive PDF ops from the agent |
 | [Fleet Guide](docs/fleet-guide.md) | **Multi-AI hub** — `/fleet listen` + `/fleet send peer.chat`, env-driven multi-provider auto-detect, Tailscale lab examples, autonomous fleet protocol |
 | [Hermes / OpenClaw Parity](docs/hermes-openclaw-parity.md) | Where Code Buddy stands vs Hermes Agent & OpenClaw — shipped capabilities, externally-gated features, and the one open code gap |

package/dist/agent/hermes-browser-backends.d.ts

@@ -63,6 +63,11 @@ export interface HermesBrowserBackendSmokeResult {
     status: HermesBrowserSmokeStatus;
     stdout: string;
     stderr: string;
+    session?: {
+        debugUrl?: string;
+        id?: string;
+        url?: string;
+    };
 }
 /** One backend attempt made while resolving an `auto` hybrid-routed smoke. */
 export interface HermesBrowserSmokeRouteAttempt {

package/dist/agent/hermes-browser-backends.js

@@ -112,6 +112,7 @@ function browserbaseBackend(env) {
     const credentialSources = presentEnvKeys(env, ['BROWSERBASE_API_KEY', 'BROWSERBASE_PROJECT_ID']);
     const configured = credentialSources.includes('BROWSERBASE_API_KEY') &&
         credentialSources.includes('BROWSERBASE_PROJECT_ID');
+    const runnable = Boolean(stagehandVersion && configured);
     return {
         id: 'browserbase',
         label: 'Browserbase / Stagehand',
@@ -119,13 +120,19 @@ function browserbaseBackend(env) {
         status: configured ? 'configured' : stagehandVersion ? 'available' : 'missing',
         installed: Boolean(stagehandVersion),
         configured,
-        runnable: false,
+        runnable,
         command: null,
         version: stagehandVersion,
         credentialSources,
-        smokeCommand: null,
-        notes: ['Stagehand is installed locally; managed Browserbase execution still requires project credentials.'],
-        remediation: configured ? [] : ['Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID for managed browser sessions.'],
+        smokeCommand: runnable ? 'buddy hermes browser-smoke browserbase --json' : null,
+        notes: [
+            'Stagehand is installed locally; managed Browserbase execution uses a real opt-in smoke runner when project credentials are present.',
+        ],
+        remediation: runnable
+            ? []
+            : configured
+                ? ['Install @browserbasehq/stagehand before selecting Browserbase smoke runs.']
+                : ['Set BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID for managed browser sessions.'],
     };
 }
 function browserUseBackend(env) {
@@ -261,7 +268,7 @@ function browserRouteGateReason(backend) {
         return null;
     }
     if (backend.id === 'browserbase' && backend.configured) {
-        return 'Browserbase is configured but excluded from auto browser routing until Code Buddy wires a first-class managed runner.';
+        return 'Browserbase is configured but excluded from auto browser routing; use the explicit smoke runner for managed sessions.';
     }
     if (backend.id === 'browser-use' && backend.configured) {
         return 'Browser Use is configured but excluded from auto browser routing until the Nous Tool Gateway runner is wired.';
@@ -415,6 +422,122 @@ async function runRemoteCdpSmoke(now, env) {
         await browser?.close().catch(() => undefined);
     }
 }
+function resolveStagehandActivePage(stagehand) {
+    if (stagehand.page) {
+        return stagehand.page;
+    }
+    const context = stagehand.context;
+    if (!context)
+        return null;
+    if (typeof context.activePage === 'function') {
+        const activePage = context.activePage();
+        if (activePage)
+            return activePage;
+    }
+    if (typeof context.pages === 'function') {
+        return context.pages()[0] ?? null;
+    }
+    if (Array.isArray(context.pages)) {
+        return context.pages[0] ?? null;
+    }
+    return null;
+}
+async function runBrowserbaseSmoke(now, env) {
+    const started = now();
+    const startedAtMs = Date.now();
+    const apiKey = env.BROWSERBASE_API_KEY?.trim();
+    const projectId = env.BROWSERBASE_PROJECT_ID?.trim();
+    if (!apiKey || !projectId) {
+        return {
+            backendId: 'browserbase',
+            command: null,
+            durationMs: Math.max(0, Date.now() - startedAtMs),
+            finishedAt: now().toISOString(),
+            label: 'Browserbase / Stagehand',
+            ok: false,
+            output: 'BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required for browserbase smoke.',
+            startedAt: started.toISOString(),
+            status: 'not-runnable',
+            stdout: '',
+            stderr: 'BROWSERBASE_API_KEY and BROWSERBASE_PROJECT_ID are required for browserbase smoke.',
+        };
+    }
+    let stagehand = null;
+    try {
+        const { Stagehand } = await import('@browserbasehq/stagehand');
+        stagehand = new Stagehand({
+            env: 'BROWSERBASE',
+            apiKey,
+            projectId,
+            verbose: 0,
+            localBrowserLaunchOptions: {
+                headless: true,
+            },
+        });
+        await stagehand.init();
+        const page = resolveStagehandActivePage(stagehand);
+        if (!page) {
+            throw new Error('Stagehand did not expose a browser page instance.');
+        }
+        const browserPage = page;
+        if (!browserPage.goto || !browserPage.locator || !browserPage.title) {
+            throw new Error('Stagehand browser page is missing the browser APIs required for smoke validation.');
+        }
+        await browserPage.goto('data:text/html,<title>OK-HERMES-BROWSERBASE</title><h1>OK-HERMES-BROWSERBASE</h1>', {
+            waitUntil: 'domcontentloaded',
+        });
+        const title = await browserPage.title();
+        const heading = await browserPage.locator('h1').textContent?.();
+        const ok = title === 'OK-HERMES-BROWSERBASE' && heading === 'OK-HERMES-BROWSERBASE';
+        const output = `title=${title}; heading=${heading ?? ''}`;
+        return {
+            backendId: 'browserbase',
+            command: null,
+            durationMs: Math.max(0, Date.now() - startedAtMs),
+            finishedAt: now().toISOString(),
+            label: 'Browserbase / Stagehand',
+            ok,
+            output,
+            startedAt: started.toISOString(),
+            status: ok ? 'passed' : 'failed',
+            stdout: output,
+            stderr: ok ? '' : 'Unexpected Browserbase page content.',
+            session: {
+                debugUrl: stagehand.browserbaseDebugURL,
+                id: stagehand.browserbaseSessionID,
+                url: stagehand.browserbaseSessionURL,
+            },
+        };
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        return {
+            backendId: 'browserbase',
+            command: null,
+            durationMs: Math.max(0, Date.now() - startedAtMs),
+            finishedAt: now().toISOString(),
+            label: 'Browserbase / Stagehand',
+            ok: false,
+            output: message,
+            startedAt: started.toISOString(),
+            status: 'failed',
+            stdout: '',
+            stderr: message,
+            session: stagehand
+                ? {
+                    debugUrl: stagehand.browserbaseDebugURL,
+                    id: stagehand.browserbaseSessionID,
+                    url: stagehand.browserbaseSessionURL,
+                }
+                : undefined,
+        };
+    }
+    finally {
+        if (stagehand?.close) {
+            await stagehand.close().catch(() => undefined);
+        }
+    }
+}
 async function runLocalPlaywrightSmoke(now, options = {}) {
     const started = now();
     const startedAtMs = Date.now();
@@ -574,6 +697,9 @@ export async function runHermesBrowserBackendSmoke(options) {
     if (backend.id === 'remote-cdp') {
         return runRemoteCdpSmoke(now, env);
     }
+    if (backend.id === 'browserbase') {
+        return runBrowserbaseSmoke(now, env);
+    }
     if (!backend.runnable) {
         return blockedSmokeResult(backend.id, 'not-runnable', `${backend.label} is not runnable on this host.`, {
             backend,
@@ -636,6 +762,9 @@ export function renderHermesBrowserSmoke(result) {
     if (result.artifacts?.length) {
         lines.push('Artifacts:', ...result.artifacts.map((artifact) => `- ${artifact.kind}: ${artifact.path} (${artifact.sizeBytes} bytes)`));
     }
+    if (result.session) {
+        lines.push('Session:', `- id: ${result.session.id ?? 'unknown'}`, `- url: ${result.session.url ?? 'unknown'}`, `${result.session.debugUrl ? `- debug: ${result.session.debugUrl}` : '- debug: unknown'}`);
+    }
     return lines.join('\n');
 }
 //# sourceMappingURL=hermes-browser-backends.js.map

package/dist/agent/hermes-parity-manifest.js

@@ -193,8 +193,8 @@ const FEATURES = [
             'npx tsx src/index.ts tools browser-operator draft "open example.com" --json',
             'npm test -- tests/tools/vision-analyze-real.test.ts --run',
         ],
-        notes: 'Strong local browser work exists, including exact browser_vision and browser_dialog prompt-tool surfaces plus machine-readable backend readiness for local Playwright, CDP, Browserbase/Stagehand, Browser Use gateway, Firecrawl, Camofox, and session recording. A real local Playwright smoke launches Chromium, verifies page content, and writes a trace.zip recording artifact; a real remote CDP smoke attaches to a live Chrome DevTools endpoint without leaking the endpoint. Hybrid routing is now executed, not just planned: an `auto` browser smoke tries the primary safe backend and falls back through the remaining runnable safe backends in order, returning the first that passes plus a machine-readable route (servedBy/usedFallback/attempts) — proven by a real test where an unreachable CDP primary falls back to local Playwright. Complete backend parity for Camofox, Browser Use gateway mode, and managed replay is still not proven.',
-        nextWork: 'Wire first-class managed backend runners (Browserbase/Browser Use) into the executed hybrid route before claiming full Hermes browser backend parity.',
+        notes: 'Strong local browser work exists, including exact browser_vision and browser_dialog prompt-tool surfaces plus machine-readable backend readiness for local Playwright, CDP, Browserbase/Stagehand, Browser Use gateway, Firecrawl, Camofox, and session recording. A real local Playwright smoke launches Chromium, verifies page content, and writes a trace.zip recording artifact; a real remote CDP smoke attaches to a live Chrome DevTools endpoint without leaking the endpoint. Browserbase now also has an opt-in Stagehand smoke runner that can open a real page when project credentials are configured and surfaces the Browserbase session/debug URLs for replay. Hybrid routing is still executed locally and remains safe-by-default: an `auto` browser smoke tries the primary safe backend and falls back through the remaining runnable safe backends in order, returning the first that passes plus a machine-readable route (servedBy/usedFallback/attempts) — proven by a real test where an unreachable CDP primary falls back to local Playwright. Complete backend parity for Camofox, Browser Use gateway mode, and managed replay is still not proven.',
+        nextWork: 'Wire Browser Use gateway mode and managed replay into first-class runners only if those upstream contracts become available and product-relevant.',
     },
     {
         id: 'nous-portal',
@@ -259,6 +259,7 @@ const FEATURES = [
         officialSurface: 'Agentskills.io-compatible skills, hub/taps, URL install, trust/update lifecycle, curator, agent-managed skills',
         codeBuddyEvidence: [
             'src/skills/',
+            'src/skills/hub-signing.ts',
             'src/agent/research-script-skill-candidate.ts',
             'src/agent/hermes-skill-package-summary.ts',
             'src/tools/registry/skills-inspection-tools.ts',
@@ -278,6 +279,7 @@ const FEATURES = [
             'npx tsx src/index.ts skills tap list --json',
             'npx tsx src/index.ts skills update-preview <name> --json',
             'npx tsx src/index.ts skills reset <name> --approved-by <reviewer> --json',
+            'npm test -- tests/skills/hub-signing.test.ts tests/skills/hub.test.ts --run',
             'npm test -- tests/agent/research-script-skill-candidate.test.ts --run',
             'npm test -- tests/agent/hermes-skill-package-summary-real.test.ts --run',
             'npm test -- tests/tools/skills-inspection-real.test.ts --run',
@@ -285,7 +287,7 @@ const FEATURES = [
             '(cd cowork && npm test -- tests/skill-package-manager-bridge.test.ts tests/skill-package-manager-strip.test.ts tests/skills-manager-page.test.tsx --run)',
             'npm test -- tests/skills/hub.test.ts tests/commands/skills-command-real.test.ts --run',
         ],
-        notes: 'Native skill coverage is good and the exact skill_manage prompt-tool action surface now covers official create(content), edit(content), patch(old_string/new_string/file_path/replace_all), write_file, and remove_file semantics with Code Buddy review gates. `buddy hermes skills status --json` now exposes read-only SkillsHub health, missing-file/integrity status, rollback availability, and next review/repair commands from the real workspace lockfile without printing SKILL.md body previews. Candidate review plus Cowork also surface installed package state, current SKILL.md previews, candidate install-state comparisons, bounded unified and expanded side-by-side candidate diffs, reviewer-gated candidate install/overwrite, and reviewer-gated enable/disable/deprecate/rollback/reset/delete/update/patch from the real SkillsHub lockfile. Repository tap/trust management persists owner/repo taps with path and trust metadata through buddy skills tap list/add/remove/trust/refresh, direct .well-known skill catalogs are cached through buddy skills well-known <url>, remote update diff previews are available through buddy skills update-preview plus skill_manage action=preview_update, and Code Buddy reset restores tampered or missing installed skills from real hub/cache content after reviewer approval. Reset is a Code Buddy repair extension because official Hermes skill_manage does not expose a reset action. Cowork now also ships a full-page Skills Manager (cowork/src/renderer/components/skills-manager-page.tsx) reachable via Cmd/Ctrl+Shift+L and the command palette: it aggregates the installed-skill list (status/integrity + inline SKILL.md preview + all lifecycle actions) and the candidate review queue (side-by-side diffs + reviewer-gated install/overwrite) in one page over the existing IPC bridges, for daily skill operations beyond the compact cockpit strips.',
+        notes: 'Native skill coverage is good and the exact skill_manage prompt-tool action surface now covers official create(content), edit(content), patch(old_string/new_string/file_path/replace_all), write_file, and remove_file semantics with Code Buddy review gates. `buddy hermes skills status --json` now exposes read-only SkillsHub health, missing-file/integrity status, rollback availability, and next review/repair commands from the real workspace lockfile without printing SKILL.md body previews. Candidate review plus Cowork also surface installed package state, current SKILL.md previews, candidate install-state comparisons, bounded unified and expanded side-by-side candidate diffs, reviewer-gated candidate install/overwrite, and reviewer-gated enable/disable/deprecate/rollback/reset/delete/update/patch from the real SkillsHub lockfile. Repository tap/trust management persists owner/repo taps with path and trust metadata through buddy skills tap list/add/remove/trust/refresh, direct .well-known skill catalogs are cached through buddy skills well-known <url>, and their registry index can now carry an Ed25519 `signature`/`indexSignature` verified over canonical JSON against the trusted keyring. The keyring is seeded with a read-only official Code Buddy publisher public key while preserving user-added keys. Remote update diff previews are available through buddy skills update-preview plus skill_manage action=preview_update, and Code Buddy reset restores tampered or missing installed skills from real hub/cache content after reviewer approval. Reset is a Code Buddy repair extension because official Hermes skill_manage does not expose a reset action. Cowork now also ships a full-page Skills Manager (cowork/src/renderer/components/skills-manager-page.tsx) reachable via Cmd/Ctrl+Shift+L and the command palette: it aggregates the installed-skill list (status/integrity + inline SKILL.md preview + all lifecycle actions) and the candidate review queue (side-by-side diffs + reviewer-gated install/overwrite) in one page over the existing IPC bridges, for daily skill operations beyond the compact cockpit strips.',
         nextWork: 'Optional polish: live-refresh the manager list after a lifecycle action (currently a manual Refresh) via an onLifecycleComplete callback.',
     },
     {

package/dist/commands/cli/hermes-commands.js

@@ -1762,7 +1762,7 @@ function registerHermesClawCommands(hermes) {
         .option('--timeout-ms <ms>', 'WebSocket validation timeout', '5000')
         .option('--openclaw-bin <path>', 'OpenClaw CLI binary path used for local install evidence')
         .option('--skip-cli-status', 'skip openclaw gateway status --json validation')
-        .option('--skip-pending-nodes', 'skip the nodes.pending read-only validation call')
+        .option('--skip-pending-nodes', 'skip the node.pair.list read-only validation call')
         .option('--approved-by <name>', 'operator approving live upstream validation')
         .option('--apply', 'contact the OpenClaw Gateway WebSocket (otherwise dry-run)')
         .option('--yes', 'confirm live validation when used with --apply')

package/dist/commands/cli/native-engine-commands.js

@@ -969,6 +969,36 @@ export function registerFleetAutonomyCommands(program) {
         console.log(`  Manage:    systemctl --user status|stop|start|restart codebuddy-autonomy`);
         console.log(`  Remove:    buddy autonomy uninstall`);
     });
+    fleet
+        .command('service <action>')
+        .description('Control the installed autonomy service: start | stop | restart | status')
+        .option('--json', 'output JSON')
+        .action(async (action, opts) => {
+        const { ServiceInstaller } = await import('../../daemon/service-installer.js');
+        const installer = new ServiceInstaller({ serviceName: 'codebuddy-autonomy' });
+        if (action === 'status') {
+            const status = await installer.status();
+            if (opts.json) {
+                console.log(JSON.stringify({ status }, null, 2));
+                return;
+            }
+            console.log(`Autonomy service (${status.platform}): ${status.installed ? (status.running ? 'running' : 'installed, stopped') : 'not installed'}`);
+            return;
+        }
+        if (action !== 'start' && action !== 'stop' && action !== 'restart') {
+            console.error(`Invalid action "${action}" (use start|stop|restart|status).`);
+            process.exit(1);
+            return;
+        }
+        const result = await installer.control(action);
+        if (opts.json) {
+            console.log(JSON.stringify({ result }, null, 2));
+            return;
+        }
+        console.log(result.success ? `Autonomy service ${action}: ok (${result.platform})` : `Failed to ${action}: ${result.error}`);
+        if (!result.success)
+            process.exit(1);
+    });
     fleet
         .command('uninstall')
         .description('Remove the autonomous daemon systemd service')

package/dist/commands/flow.js

@@ -8,8 +8,7 @@
  *   buddy flow "Refactor the API layer" --max-retries 2
  */
 import { Command } from 'commander';
-import { getSettingsManager } from '../utils/settings-manager.js';
-import { PROVIDERS } from './provider.js';
+import { resolveCommandProvider } from './llm-provider-resolution.js';
 function extractContent(response) {
     return response.choices?.[0]?.message?.content || '';
 }
@@ -20,24 +19,21 @@ export function createFlowCommand() {
         .option('--max-retries <n>', 'Max retries per failed step', '1')
         .option('--default-agent <key>', 'Default agent key', 'default')
         .option('--verbose', 'Show step-by-step progress', false)
-        .action(async (goal, options) => {
-        const settingsManager = getSettingsManager();
-        const userSettings = settingsManager.loadUserSettings();
-        const currentProviderKey = userSettings.provider || 'grok';
-        const providerInfo = PROVIDERS[currentProviderKey];
-        let apiKey = process.env[providerInfo?.envVar || ''] || '';
-        if (!apiKey)
-            apiKey = process.env.GROK_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || '';
-        if (!apiKey) {
-            console.error('Error: No API key configured. Run: buddy onboard');
+        .option('-m, --model <model>', 'Override the model for this flow run')
+        .action(async (goal, options, command) => {
+        // The root program also declares a global `-m, --model`; depending on
+        // argv order Commander can bind it there — merge so either wins.
+        const modelOverride = options.model ?? command?.optsWithGlobals?.()?.model;
+        const resolved = resolveCommandProvider({ explicitModel: modelOverride });
+        if (!resolved) {
+            console.error('Error: No provider available — set an API key, run `buddy onboard`, or point CODEBUDDY_PROVIDER=ollama at a local Ollama.');
             process.exit(1);
         }
         console.log(`\n  Planning Flow: "${goal}"\n`);
         try {
             const { PlanningFlow } = await import('../agent/flow/planning-flow.js');
             const { CodeBuddyClient } = await import('../codebuddy/client.js');
-            const model = settingsManager.getCurrentModel() || providerInfo?.defaultModel;
-            const client = new CodeBuddyClient(apiKey, model, providerInfo?.baseURL);
+            const client = new CodeBuddyClient(resolved.apiKey, resolved.model, resolved.baseURL);
             // Plan with LLM function
             const planWithLLM = async (prompt) => {
                 const response = await client.chat([

package/dist/commands/llm-provider-resolution.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Shared provider resolution for one-shot LLM CLI commands
+ * (`buddy research`, `buddy flow`).
+ *
+ * Historically these commands resolved ONLY through the settings
+ * provider + the `PROVIDERS` map (paid keys), so a machine running on
+ * local Ollama (`CODEBUDDY_PROVIDER=ollama`, $0) hit the "no API key"
+ * exit even though the rest of Code Buddy — including the autonomous
+ * daemon — runs fine there. This resolver keeps the legacy path first
+ * (backward compatible) and falls back to {@link detectProviderFromEnv}
+ * (ollama / chatgpt-oauth / env-detected providers) when either:
+ *   - `CODEBUDDY_PROVIDER` is explicitly set (operator intent wins), or
+ *   - the legacy path found no key.
+ */
+export interface ResolvedCommandProvider {
+    apiKey: string;
+    baseURL?: string;
+    model?: string;
+    /** Human-readable provider name for progress output. */
+    providerLabel: string;
+}
+export declare function resolveCommandProvider(options?: {
+    explicitModel?: string;
+}): ResolvedCommandProvider | null;

package/dist/commands/llm-provider-resolution.js

@@ -0,0 +1,73 @@
+/**
+ * Shared provider resolution for one-shot LLM CLI commands
+ * (`buddy research`, `buddy flow`).
+ *
+ * Historically these commands resolved ONLY through the settings
+ * provider + the `PROVIDERS` map (paid keys), so a machine running on
+ * local Ollama (`CODEBUDDY_PROVIDER=ollama`, $0) hit the "no API key"
+ * exit even though the rest of Code Buddy — including the autonomous
+ * daemon — runs fine there. This resolver keeps the legacy path first
+ * (backward compatible) and falls back to {@link detectProviderFromEnv}
+ * (ollama / chatgpt-oauth / env-detected providers) when either:
+ *   - `CODEBUDDY_PROVIDER` is explicitly set (operator intent wins), or
+ *   - the legacy path found no key.
+ */
+import { getSettingsManager } from '../utils/settings-manager.js';
+import { detectProviderFromEnv } from '../utils/provider-detector.js';
+import { PROVIDERS } from './provider.js';
+export function resolveCommandProvider(options = {}) {
+    const detectFirst = Boolean(process.env.CODEBUDDY_PROVIDER);
+    if (detectFirst) {
+        const detected = fromEnvDetection(options.explicitModel);
+        if (detected)
+            return detected;
+    }
+    const settingsManager = getSettingsManager();
+    const settings = settingsManager.loadUserSettings();
+    const currentProviderKey = settings.provider || 'grok';
+    const providerInfo = PROVIDERS[currentProviderKey];
+    let apiKey = process.env[providerInfo?.envVar || ''] || '';
+    if (!apiKey && currentProviderKey === 'grok')
+        apiKey = process.env.XAI_API_KEY || '';
+    if (!apiKey && currentProviderKey === 'gemini')
+        apiKey = process.env.GOOGLE_API_KEY || '';
+    if (!apiKey) {
+        apiKey =
+            process.env.GROK_API_KEY ||
+                process.env.ANTHROPIC_API_KEY ||
+                process.env.OPENAI_API_KEY ||
+                process.env.GOOGLE_API_KEY ||
+                '';
+    }
+    if (apiKey) {
+        const providerEnvBaseURL = {
+            grok: process.env.GROK_BASE_URL,
+            claude: process.env.ANTHROPIC_BASE_URL,
+            openai: process.env.OPENAI_BASE_URL,
+            gemini: process.env.GEMINI_BASE_URL,
+        };
+        return {
+            apiKey,
+            baseURL: providerEnvBaseURL[currentProviderKey] || providerInfo?.baseURL,
+            model: options.explicitModel ||
+                settingsManager.getCurrentModel() ||
+                providerInfo?.defaultModel,
+            providerLabel: providerInfo?.name || currentProviderKey,
+        };
+    }
+    // Legacy path found nothing — fall back to env detection (local
+    // Ollama, ChatGPT OAuth, …) so a $0 local machine can still run.
+    return fromEnvDetection(options.explicitModel);
+}
+function fromEnvDetection(explicitModel) {
+    const detected = detectProviderFromEnv();
+    if (!detected)
+        return null;
+    return {
+        apiKey: detected.apiKey,
+        baseURL: detected.baseURL,
+        model: explicitModel || detected.defaultModel,
+        providerLabel: detected.provider,
+    };
+}
+//# sourceMappingURL=llm-provider-resolution.js.map

package/dist/commands/research/index.js

@@ -14,8 +14,7 @@ import { WideResearchOrchestrator } from '../../agent/wide-research.js';
 import * as fs from 'fs/promises';
 import * as fsSync from 'fs';
 import path from 'path';
-import { getSettingsManager } from '../../utils/settings-manager.js';
-import { PROVIDERS } from '../provider.js';
+import { resolveCommandProvider } from '../llm-provider-resolution.js';
 async function runDirectResearch(topic, apiKey, providerConfig, timeoutMs) {
     const { CodeBuddyClient } = await import('../../codebuddy/client.js');
     const client = new CodeBuddyClient(apiKey, providerConfig.model, providerConfig.baseURL);
@@ -67,31 +66,21 @@ export function createResearchCommand() {
         .option('--timeout-ms <n>', 'Overall research timeout in milliseconds (default: 300000)', '300000')
         .option('-f, --report <file>', 'Save the report to a Markdown file')
         .option('--context <text>', 'Additional context injected into each worker')
-        .action(async (topic, opts) => {
-        const settingsManager = getSettingsManager();
-        const settings = settingsManager.loadUserSettings();
-        const currentProviderKey = settings.provider || 'grok';
-        const providerInfo = PROVIDERS[currentProviderKey];
-        let apiKey = process.env[providerInfo?.envVar || ''] || '';
-        if (!apiKey && currentProviderKey === 'grok')
-            apiKey = process.env.XAI_API_KEY || '';
-        if (!apiKey && currentProviderKey === 'gemini')
-            apiKey = process.env.GOOGLE_API_KEY || '';
-        if (!apiKey)
-            apiKey = process.env.GROK_API_KEY || process.env.ANTHROPIC_API_KEY || process.env.OPENAI_API_KEY || process.env.GOOGLE_API_KEY || '';
-        if (!apiKey) {
-            console.error('❌ No API key found for the active provider. Set the appropriate environment variable.');
+        .option('-m, --model <model>', 'Override the model for this research run')
+        .option('--wide', 'Force parallel workers even in non-interactive runs (default: direct single-pass)', false)
+        .action(async (topic, opts, command) => {
+        // The root program also declares a global `-m, --model`; depending on
+        // argv order Commander can bind it there — merge so either wins.
+        const modelOverride = opts.model ?? command?.optsWithGlobals?.()?.model;
+        const resolved = resolveCommandProvider({ explicitModel: modelOverride });
+        if (!resolved) {
+            console.error('❌ No provider available — set an API key, run `buddy login`, or point CODEBUDDY_PROVIDER=ollama at a local Ollama.');
             process.exit(1);
         }
-        const providerEnvBaseURL = {
-            grok: process.env.GROK_BASE_URL,
-            claude: process.env.ANTHROPIC_BASE_URL,
-            openai: process.env.OPENAI_BASE_URL,
-            gemini: process.env.GEMINI_BASE_URL,
-        };
+        const apiKey = resolved.apiKey;
         const providerConfig = {
-            model: settingsManager.getCurrentModel() || providerInfo?.defaultModel,
-            baseURL: providerEnvBaseURL[currentProviderKey] || providerInfo?.baseURL,
+            model: resolved.model,
+            baseURL: resolved.baseURL,
         };
         const workers = Math.min(parseInt(opts.workers, 10) || 5, 20);
         const maxRoundsPerWorker = parseInt(opts.rounds, 10) || 15;
@@ -101,7 +90,7 @@ export function createResearchCommand() {
         const argvReportPath = detectReportPathFromArgv(process.argv.slice(2));
         const reportPath = opts.report || argvReportPath;
         console.log(`\n🔬 Wide Research: "${topic}"`);
-        console.log(`   Provider: ${providerInfo?.name || currentProviderKey} | Model: ${providerConfig.model}`);
+        console.log(`   Provider: ${resolved.providerLabel} | Model: ${providerConfig.model}`);
         console.log(`   Workers: ${workers}  |  Max rounds per worker: ${maxRoundsPerWorker}`);
         console.log('─'.repeat(60));
         if (!opts.report && reportPath) {
@@ -109,7 +98,9 @@ export function createResearchCommand() {
         }
         // In non-interactive runs (CI/headless), prefer a direct single-pass research call.
         // This avoids long-lived worker handles and makes output deterministic for automation.
-        if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        // `--wide` opts back into the parallel-worker mode (a GUI subprocess is
+        // non-TTY but may legitimately want the full Manus-style fan-out).
+        if (!opts.wide && (!process.stdin.isTTY || !process.stdout.isTTY)) {
             console.log('ℹ️ Non-interactive mode detected, using direct research mode.');
             try {
                 const report = await runDirectResearch(topic, apiKey, providerConfig, Math.min(overallTimeoutMs, 120_000));
@@ -118,7 +109,7 @@ export function createResearchCommand() {
                     ``,
                     `Generated: ${new Date().toISOString()}`,
                     `Mode: direct`,
-                    `Provider: ${providerInfo?.name || currentProviderKey}`,
+                    `Provider: ${resolved.providerLabel}`,
                     `Model: ${providerConfig.model || 'default'}`,
                     ``,
                     `---`,

package/dist/daemon/autonomous-loop.d.ts

@@ -39,7 +39,7 @@ export interface AutonomousLoopConfig {
     enabled?: () => boolean;
 }
 export interface TickResult {
-    outcome: 'disabled' | 'idle' | 'completed' | 'failed';
+    outcome: 'disabled' | 'idle' | 'completed' | 'failed' | 'saturated';
     taskId?: string;
     taskTitle?: string;
     model?: AutonomousModelChoice;

package/dist/daemon/autonomous-loop.js

@@ -21,6 +21,7 @@
  * arbitration stays "first to push wins" per the fleet protocol.
  */
 import { chooseAutonomousModel, } from '../agent/model-tier.js';
+import { beginFleetWork, isFleetSaturated } from '../fleet/fleet-load.js';
 export class FleetAutonomousLoop {
     store;
     tierConfig;
@@ -46,6 +47,16 @@ export class FleetAutonomousLoop {
         if (!this.enabled()) {
             return { outcome: 'disabled' };
         }
+        // Saturation backpressure (fleet load balancing): when this peer is
+        // at its configured capacity (CODEBUDDY_FLEET_MAX_CONCURRENCY), it
+        // ABSTAINS from claiming. The colab queue is shared across machines,
+        // so an idle peer's daemon wins the claim instead — utilization
+        // spreads over the fleet without any new RPC. Opt-in: with no
+        // configured capacity this never triggers.
+        if (isFleetSaturated()) {
+            this.store.updatePresence({ status: 'active' });
+            return { outcome: 'saturated', detail: 'at capacity — leaving the queue to idle peers' };
+        }
         this.store.updatePresence({ status: 'active' });
         const next = this.store.nextClaimable();
         if (!next) {
@@ -66,12 +77,16 @@ export class FleetAutonomousLoop {
         const failures = this.failures.get(task.id) ?? 0;
         const model = chooseAutonomousModel(this.tierConfig, { priority: task.priority, ...(failures > 0 ? { failures } : {}) }, this.policy);
         let result;
+        const doneLoad = beginFleetWork('autonomy.task');
         try {
             result = await this.executor(task, model);
         }
         catch (err) {
             result = { ok: false, summary: 'executor threw', error: err instanceof Error ? err.message : String(err) };
         }
+        finally {
+            doneLoad();
+        }
         if (result.ok) {
             this.failures.delete(task.id);
             this.store.completeTask(task.id, {

package/dist/daemon/service-installer.d.ts

@@ -26,11 +26,25 @@ export interface ServiceInstallResult {
     instructions?: string;
     error?: string;
 }
+export type ServiceControlAction = 'start' | 'stop' | 'restart';
+export interface ServiceControlResult {
+    success: boolean;
+    action: ServiceControlAction;
+    platform: string;
+    error?: string;
+}
 export declare class ServiceInstaller {
     private config;
     constructor(config?: Partial<ServiceInstallerConfig>);
     install(): Promise<ServiceInstallResult>;
     uninstall(): Promise<ServiceInstallResult>;
+    /**
+     * Start/stop/restart the installed service through the platform's service
+     * manager (systemd user unit, launchd plist, Task Scheduler task). Fails
+     * cleanly when the service isn't installed — install() is the only way to
+     * create it.
+     */
+    control(action: ServiceControlAction): Promise<ServiceControlResult>;
     status(): Promise<{
         installed: boolean;
         running: boolean;