Skip to content

an open-source alternative to the dots, bots and muses of the world, run an office of claude code/codex like agents on your laptop, sandboxes or anywhere, uses your existing subscriptions

fix(onboarding): check engine availability before the pick is committed

Chaitanya Giri7903ae908da8
diff --git a/package.json b/package.json
index 97bb375a..63d9f75a 100644
--- a/package.json
+++ b/package.json
@@ -19,7 +19,7 @@
"typecheck:node": "tsc --noEmit -p tsconfig.node.json",
"typecheck:web": "tsc --noEmit -p tsconfig.web.json",
"typecheck": "npm run typecheck:node && npm run typecheck:web",
- "test:focused": "node --test test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs",
+ "test:focused": "node --test test/engine-availability.test.cjs test/codex-remote.test.cjs test/control.test.cjs test/provider-automation.test.cjs test/provider-config.test.cjs test/queue-delivery.test.cjs test/terminal-automation.test.cjs test/terminal-recovery.test.cjs test/terminal-selection.test.cjs test/roster.test.cjs test/proc-kill.test.cjs test/expand-tilde.test.cjs test/hive-cwd.test.cjs test/hive-task-mutation.test.cjs test/hive-hook-node.test.cjs test/hive-roster-injection.test.cjs test/hive-runtime-path.test.cjs test/cli-install-ladder.test.cjs test/node-install.test.cjs test/office-gl-recovery.test.cjs test/update-state.test.cjs test/release-notes.test.cjs test/transcript-project-dir.test.cjs test/commit-graph.test.cjs test/ide-image.test.cjs test/win-cmd-shim.test.cjs test/hive-windows-prompt.test.cjs test/release-drop.test.cjs test/skills.test.cjs test/skills-install.test.cjs test/hero-payload.test.cjs",
"check:links": "node tools/check-release-links.cjs",
"dist": "npm run build && electron-builder",
"dist:mac": "npm run build && electron-builder --mac",
diff --git a/src/renderer/src/components/OnboardingWizard.tsx b/src/renderer/src/components/OnboardingWizard.tsx
index 6f8979e4..bd6ba81b 100644
--- a/src/renderer/src/components/OnboardingWizard.tsx
+++ b/src/renderer/src/components/OnboardingWizard.tsx
@@ -6,6 +6,10 @@ import { SpritePortrait } from './SpritePortrait';
import { ProviderLogo } from './ProviderLogo';
import { AGENT_PROVIDER_PRESETS, modelsForProvider, type AgentProvider, type HarnessConfig } from '@/store/config';
import { canReceiveInbox, providerPreset } from '@shared/agentProvider';
+import {
+ classifyEngineAvailability, engineAvailabilityBadge, engineAvailabilityMessage, engineBlocksOnboarding
+} from '@shared/engineAvailability';
+import type { ToolStatus } from '@shared/toolCatalog';
export interface OnboardingWizardProps {
onComplete: (config: HarnessConfig) => void;
@@ -99,6 +103,23 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
const [error, setError] = useState<string | undefined>();
const [busy, setBusy] = useState(false);
+ // Which engine CLIs are actually on this machine. The picker used to record the
+ // choice blind; the first check happened when Michael spawned, and for a
+ // provider with no installer that meant a first run where nothing ever booted.
+ // `undefined` = probe not back yet (or failed): rows show no badge and nothing
+ // is blocked, because a broken probe must not lock a new user out.
+ const [engines, setEngines] = useState<ToolStatus[] | undefined>();
+ const [probing, setProbing] = useState(false);
+ const probeEngines = async () => {
+ setProbing(true);
+ try { setEngines(await window.cth.toolsStatus()); }
+ catch { /* leave undefined: unknown, never blocking */ }
+ finally { setProbing(false); }
+ };
+ useEffect(() => { void probeEngines(); }, []);
+ const selectedEngine = classifyEngineAvailability(engines, godProvider);
+ const engineBlocked = engineBlocksOnboarding(selectedEngine);
+
// Permissions & reliability toggles. These apply IMMEDIATELY on change (their
// own IPC / OS state) — they are NOT part of finish()'s config write. First-run
// defaults: notifications off (config default), login-item off (fresh install);
@@ -163,6 +184,13 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
setError(undefined);
const harnessHome = home.trim(); // whitespace-only is not a folder
if (!harnessHome) { setError('Pick a harness home folder first.'); setBusy(false); setStep('home'); return; }
+ // The orchestrator step already refuses to advance on this, but a late probe
+ // result can change the answer after the user has moved on. Never write a
+ // godProvider that is known to be unable to boot.
+ if (engineBlocked) {
+ setError(`${providerPreset(godProvider).label} is not installed. Install it and press "check again", or pick another engine.`);
+ setBusy(false); setStep('orchestrator'); return;
+ }
const ensure = await window.cth.ensureHarnessHome(harnessHome);
if (!ensure.ok) {
setError(ensure.error ?? 'could not create harness home');
@@ -393,10 +421,12 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
one that runs your whole office. We recommend Claude Code on Opus 4.8 (1M).
You can add or switch the others later.</>
) : (
- <>Each option is a <strong>CLI engine</strong> you have installed (Claude Code,
- Codex, Antigravity/Gemini, or a local proxy like Qwen).
+ <>Each option is a <strong>CLI engine</strong> (Claude Code, Codex,
+ Antigravity/Gemini, or a local proxy like Qwen). Engines marked
+ INSTALLED are already on this machine; INSTALLS ON FIRST RUN means the app
+ sets it up when Michael first starts.
<strong> Your clone</strong> (Michael) is the engine that orchestrates the whole
- hive. Recommended: Claude Code · Opus 4.8 · 1M — other providers can be wired
+ hive. Recommended: Claude Code · Opus 4.8 · 1M. Other providers can be wired
per agent later.</>
)}
</span>
@@ -442,6 +472,21 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
</span>
)}
</span>
+ {(() => {
+ const a = classifyEngineAvailability(engines, p.id);
+ const badge = engineAvailabilityBadge(a);
+ if (!badge) return null;
+ const bad = a.state === 'not-installable';
+ return (
+ <span title={a.path ?? undefined} style={{
+ fontSize: 10, padding: '1px 5px', lineHeight: '16px',
+ background: a.state === 'installed' ? 'var(--cth-mint-light)' : bad ? 'var(--cth-paper-100)' : 'var(--cth-cream-200)',
+ color: bad ? 'var(--cth-ink-500)' : 'var(--cth-ink-900)',
+ boxShadow: 'inset 0 0 0 1px var(--cth-ink-300)',
+ fontFamily: 'var(--cth-font-display)', flexShrink: 0
+ }}>{badge}</span>
+ );
+ })()}
{p.id === 'claude' && (
<span style={{
fontSize: 10, padding: '1px 5px', lineHeight: '16px',
@@ -454,6 +499,25 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
);
})}
</div>
+ {engineBlocked && (
+ <div style={{
+ display: 'flex', flexDirection: 'column', gap: 8, padding: 10,
+ background: 'var(--cth-paper-100)', boxShadow: 'inset 0 0 0 2px var(--cth-ink-900)',
+ fontSize: 12, lineHeight: '17px', color: 'var(--cth-ink-900)'
+ }}>
+ <span>{engineAvailabilityMessage(selectedEngine, providerPreset(godProvider).label)}</span>
+ <div style={{ display: 'flex', gap: 8, alignItems: 'center', flexWrap: 'wrap' }}>
+ <PixelButton variant="secondary" size="sm" onClick={() => { void probeEngines(); }} disabled={probing}>
+ {probing ? 'checking...' : 'check again'}
+ </PixelButton>
+ {selectedEngine.docsUrl && (
+ <PixelButton variant="ghost" size="sm" onClick={() => { void window.cth.openExternal(selectedEngine.docsUrl!); }}>
+ install instructions
+ </PixelButton>
+ )}
+ </div>
+ </div>
+ )}
<div style={{ display: 'flex', flexDirection: 'column', gap: 4 }}>
<div style={{ fontSize: 12, color: 'var(--cth-ink-500)' }}>Model</div>
<select
@@ -697,10 +761,17 @@ export function OnboardingWizard({ onComplete }: OnboardingWizardProps) {
setError('Pick a harness home folder first.');
return;
}
+ // Same idea for the engine: refuse here, with the reason on
+ // screen, instead of letting a pick that cannot boot through
+ // to a Michael that never starts.
+ if (step === 'orchestrator' && engineBlocked) {
+ setError(`${providerPreset(godProvider).label} is not installed. Install it and press "check again", or pick another engine.`);
+ return;
+ }
setError(undefined);
setStep(nextStep(step));
}}
- disabled={step === 'persona' && !audience}
+ disabled={(step === 'persona' && !audience) || (step === 'orchestrator' && engineBlocked)}
>
{step === 'welcome' ? 'set it up' : 'next'}
</PixelButton>
diff --git a/src/shared/engineAvailability.ts b/src/shared/engineAvailability.ts
new file mode 100644
index 00000000..f0497cd3
--- /dev/null
+++ b/src/shared/engineAvailability.ts
@@ -0,0 +1,78 @@
+/**
+ * Can the engine a user is about to pick actually boot on this machine?
+ *
+ * The onboarding wizard records Michael's engine and nothing checks it until the
+ * first spawn. spawnAgentCore then runs the install ladder (cliInstall.ts), and
+ * for a provider with no `installCommand` and no `nativeInstallCommand` that
+ * ladder ends at the `manual` rung: a hint is printed in a terminal and the
+ * orchestrator never starts. This module turns the setup catalog probe
+ * (`tools:status`, which already resolves every engine binary on PATH) into one
+ * answer per provider so the wizard can say so BEFORE the pick is committed.
+ *
+ * Pure and electron-free on purpose so it is testable from node --test.
+ */
+import type { AgentProvider } from './agentProvider';
+import type { ToolStatus } from './toolCatalog';
+
+export type EngineAvailabilityState =
+ /** The binary resolves on this machine. */
+ | 'installed'
+ /** Not here yet, but the provider ships an installer the app runs on first spawn. */
+ | 'installs-on-first-run'
+ /** Not here and nothing we can run: the user has to install it by hand first. */
+ | 'not-installable'
+ /** The probe did not run or did not cover this provider. Never block on this. */
+ | 'unknown';
+
+export interface EngineAvailability {
+ state: EngineAvailabilityState;
+ /** Absolute path when installed. */
+ path: string | null;
+ /** The command the app would run (or the user could paste) to install it. */
+ installCommand: string;
+ docsUrl?: string;
+}
+
+/** Classify one provider from the catalog probe. `statuses` is what
+ * `window.cth.toolsStatus()` returned; undefined means it has not run (yet). */
+export function classifyEngineAvailability(
+ statuses: readonly ToolStatus[] | undefined,
+ provider: AgentProvider
+): EngineAvailability {
+ const row = statuses?.find((s) => s.id === `engine:${provider}`);
+ if (!row) return { state: 'unknown', path: null, installCommand: '' };
+ const installCommand = row.installCommand ?? '';
+ if (row.found) return { state: 'installed', path: row.path, installCommand, docsUrl: row.docsUrl };
+ return {
+ state: installCommand ? 'installs-on-first-run' : 'not-installable',
+ path: null,
+ installCommand,
+ docsUrl: row.docsUrl
+ };
+}
+
+/** Whether the wizard must refuse to move on with this engine selected. Only the
+ * proven dead end blocks; an unknown probe never locks a user out. */
+export function engineBlocksOnboarding(a: EngineAvailability): boolean {
+ return a.state === 'not-installable';
+}
+
+/** One short line for the badge on each engine row. */
+export function engineAvailabilityBadge(a: EngineAvailability): string | null {
+ switch (a.state) {
+ case 'installed': return 'INSTALLED';
+ case 'installs-on-first-run': return 'INSTALLS ON FIRST RUN';
+ case 'not-installable': return 'NOT INSTALLED';
+ default: return null;
+ }
+}
+
+/** The explanation shown under the picker when the selected engine cannot boot.
+ * Written for someone who does not know what a CLI engine is: what happened,
+ * then what to do next. */
+export function engineAvailabilityMessage(a: EngineAvailability, label: string): string | null {
+ if (a.state !== 'not-installable') return null;
+ return `${label} is not installed on this computer and the app has no installer for it, ` +
+ `so Michael could not start. Install it first, then press "check again". ` +
+ `Or pick Claude Code, which installs itself on first run.`;
+}
diff --git a/test/engine-availability.test.cjs b/test/engine-availability.test.cjs
new file mode 100644
index 00000000..65d170b0
--- /dev/null
+++ b/test/engine-availability.test.cjs
@@ -0,0 +1,75 @@
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const loadTs = require('./load-ts.cjs');
+
+const {
+ classifyEngineAvailability,
+ engineBlocksOnboarding,
+ engineAvailabilityBadge,
+ engineAvailabilityMessage
+} = loadTs('src/shared/engineAvailability.ts');
+const { toolCatalog } = loadTs('src/shared/toolCatalog.ts');
+const { AGENT_PROVIDER_PRESETS, canReceiveInbox } = loadTs('src/shared/agentProvider.ts');
+
+// Build what `tools:status` returns for a machine where `found` lists the only
+// binaries present. Mirrors the main-process handler's shape without electron.
+function statusesFor(found) {
+ return toolCatalog().map((spec) => ({
+ ...spec,
+ installCommand: spec.install.posix,
+ found: !!spec.bin && found.includes(spec.bin),
+ path: spec.bin && found.includes(spec.bin) ? `/usr/local/bin/${spec.bin}` : null
+ }));
+}
+
+test('an installed engine is installed, whatever its installer story', () => {
+ const s = statusesFor(['claude', 'grok']);
+ assert.equal(classifyEngineAvailability(s, 'claude').state, 'installed');
+ assert.equal(classifyEngineAvailability(s, 'grok').state, 'installed');
+ assert.equal(classifyEngineAvailability(s, 'grok').path, '/usr/local/bin/grok');
+});
+
+test('a missing engine with an installer installs on first run and does not block', () => {
+ const s = statusesFor([]);
+ for (const id of ['claude', 'codex', 'opencode', 'crush', 'pi', 'copilot']) {
+ const a = classifyEngineAvailability(s, id);
+ assert.equal(a.state, 'installs-on-first-run', id);
+ assert.ok(a.installCommand.length > 0, id);
+ assert.equal(engineBlocksOnboarding(a), false, id);
+ }
+});
+
+test('the repro: grok, antigravity and qwen are offered by the wizard but cannot install', () => {
+ const s = statusesFor([]);
+ const offered = AGENT_PROVIDER_PRESETS.filter((p) => canReceiveInbox(p.id)).map((p) => p.id);
+ for (const id of ['grok', 'antigravity', 'qwen']) {
+ assert.ok(offered.includes(id), `${id} is on the picker`);
+ const a = classifyEngineAvailability(s, id);
+ assert.equal(a.state, 'not-installable', id);
+ assert.equal(engineBlocksOnboarding(a), true, id);
+ assert.equal(engineAvailabilityBadge(a), 'NOT INSTALLED');
+ const msg = engineAvailabilityMessage(a, 'Grok');
+ assert.match(msg, /not installed/);
+ assert.match(msg, /check again/);
+ assert.match(msg, /Claude Code/);
+ assert.doesNotMatch(msg, /[–—-]/, 'no dashes in user facing prose');
+ }
+});
+
+test('no probe result means unknown, and unknown never blocks', () => {
+ const a = classifyEngineAvailability(undefined, 'grok');
+ assert.equal(a.state, 'unknown');
+ assert.equal(engineBlocksOnboarding(a), false);
+ assert.equal(engineAvailabilityBadge(a), null);
+ assert.equal(engineAvailabilityMessage(a, 'Grok'), null);
+ // a probe that ran but lacks the row behaves the same
+ assert.equal(classifyEngineAvailability([], 'grok').state, 'unknown');
+});
+
+test('only the dead end has a message', () => {
+ const s = statusesFor(['claude']);
+ assert.equal(engineAvailabilityMessage(classifyEngineAvailability(s, 'claude'), 'Claude Code'), null);
+ assert.equal(engineAvailabilityMessage(classifyEngineAvailability(s, 'codex'), 'Codex'), null);
+});