@gaia-ai/conductor 0.5.5 → 0.6.1

package/dist/src/commands/conductor.d.ts

@@ -0,0 +1,57 @@
+import { type ConductorLogger, type GaiaCommandHost, type GaiaCommandPlugin } from '@gaia-ai/core';
+import { Command } from 'commander';
+import type { GaiaExecutor } from '../plugins/executor.js';
+import { type ResolvedAgent } from '../plugins/plugins.js';
+import type { GaiaRemote } from '../plugins/remote.js';
+import type { GaiaWorkspace } from '../plugins/workspace.js';
+import type { ConductorFileConfig } from '../types.js';
+/** Test seam: inject any subset of dependencies. */
+export interface GaiaCliDeps {
+    remote?: GaiaRemote;
+    executor?: GaiaExecutor;
+    workspace?: GaiaWorkspace;
+    agents?: ResolvedAgent[];
+    config?: ConductorFileConfig;
+    /** Injectable registry fetch for the start-time version check (tests). */
+    fetch?: typeof fetch;
+    /** Host contract (resolveBases); default: this install + cwd. */
+    host?: GaiaCommandHost;
+    /**
+     * GAIA-222: the herdr process host behind `start` / `stop`. Defaults to the
+     * real shell-out (`realHerdrHost`) — a test MUST inject a fake, or the suite
+     * creates real workspaces + real conductor processes on the developer's
+     * machine.
+     */
+    herdr?: HerdrHost;
+}
+/**
+ * The multiplexer seam of the conductor lifecycle: start a detached foreground
+ * loop, and kill it again by its handle. One interface so both directions are
+ * injectable — `killViaHerdr` is reached by BOTH `stop` and `stop --now`.
+ */
+export interface HerdrHost {
+    spawn(label: string, cwd: string, cmd: string): Promise<void>;
+    kill(label: string): Promise<void>;
+}
+export declare function parseHerdrJson(output: string, command: string): unknown;
+/** The production host: the real `herdr` binary. */
+export declare const realHerdrHost: HerdrHost;
+/**
+ * Start-time auth gate. Returns true if authenticated (session or session-less
+ * provider); otherwise logs a single clear line and returns false.
+ */
+export declare function ensureAuthenticated(config: ConductorFileConfig, logger: ConductorLogger): Promise<boolean>;
+/** Build the `conductor` subcommand tree (lifecycle + registry + init). */
+export declare function createConductorCommand(deps: GaiaCliDeps): Command;
+/** The `conductor` command plugin the host mounts (GAIA-201). GAIA-224
+ *  (Finding 7): the `gaia deployment` batch helper is no longer registered here —
+ *  it is its own command addon, `@gaia-ai/addon-deployment`. */
+declare const conductorCommandPlugin: GaiaCommandPlugin;
+export default conductorCommandPlugin;
+/**
+ * Build a standalone program with the conductor command mounted — the test entry
+ * (mirrors what the host does for `gaia conductor …`). `deps` inject fakes.
+ */
+export declare function buildConductorProgram(deps?: GaiaCliDeps): Command;
+/** Parse argv against the conductor program (test entry). */
+export declare function runConductorCli(argv: string[], deps?: GaiaCliDeps): Promise<void>;

package/dist/src/{cli/gaia.js → commands/conductor.js}

@@ -1,29 +1,34 @@
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { CommandRunner, createLogger, exec, setDefaultCommandRunner, } from '@gaia-ai/core';
-import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+import { CommandRunner, createLogger, exec, getRegisteredConductor, listRegisteredConductors, loadGaiaConfig, machineContextPath, readMachineContext, registerConductor, removeConductor, resolveConfigPath, setDefaultCommandRunner, } from '@gaia-ai/core';
 import { Command } from 'commander';
-import { authStatus, buildProgram as buildDropshProgram } from 'dropsh';
-import { loadConductorConfig, resolveConfigPath } from '../config.js';
+import { authStatus } from 'dropsh';
+import { scaffold } from '../cli/init.js';
+import { runUpgrade } from '../cli/upgrade.js';
+import { fetchUpdateNotice, printVersionLine } from '../cli/version-check.js';
+import { composeConductorConfig, loadConductorConfig } from '../config.js';
 import { Conductor } from '../core/conductor.js';
-import { machineContextPath, readMachineContext, scaffold, } from './init.js';
-import * as registry from './local-registry.js';
-import { fetchUpdateNotice, printVersionLine, resolveCliVersion, runUpdate, } from './version-check.js';
+import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
+/** Default host bases for connection/plugin resolution when none is injected. */
+function defaultHost() {
+    return { resolveBases: [import.meta.url, `${process.cwd()}/`] };
+}
 /**
- * Default config path. `--config` / `$GAIA_CONDUCTOR_CONFIG` win; otherwise walk
- * up from cwd to the nearest `.gaia/conductor.config.js` (git/eslint style), so a
- * `gaia` command works from any subdirectory of a project/worktree. Throws an
- * actionable error when nothing is found up the tree (see resolveConfigPath).
+ * Resolve + compose the full conductor config: the engine half
+ * (`conductor.config.js` via `loadConductorConfig`) plus the connection half
+ * (`gaia.config.js` via `loadGaiaConfig`, walk-up → home → shipped fallback).
+ * `--config` / `$GAIA_CONDUCTOR_CONFIG` selects the engine file; the connection
+ * is resolved from cwd.
  */
-function defaultConfigPath(override) {
-    return resolveConfigPath(override);
-}
 async function resolveConfig(deps, configPathOverride) {
     if (deps.config) {
         return deps.config;
     }
-    return loadConductorConfig(defaultConfigPath(configPathOverride));
+    const host = deps.host ?? defaultHost();
+    const engine = await loadConductorConfig(resolveConfigPath(configPathOverride));
+    const connection = await loadGaiaConfig(host, {});
+    return composeConductorConfig(engine, connection);
 }
 async function resolveRemote(deps, config) {
     return deps.remote ?? (await selectRemote(config));
@@ -33,9 +38,8 @@ function checkoutRootOf(config) {
 }
 /**
  * The conductor's stable identity (gaia_conductor.machine_id). machine_id is
- * required — the loader (loadConductorConfig) throws without it — so lifecycle
- * commands read it here, never re-derive. A config not built by the loader that
- * somehow lacks it fails loudly rather than silently minting a divergent id.
+ * required — the loader throws without it — so lifecycle commands read it here,
+ * never re-derive.
  */
 function conductorIdOf(config) {
     const id = config.machine_id;
@@ -58,7 +62,7 @@ function loggerFor(checkoutRoot, log = {}) {
     setDefaultCommandRunner(new CommandRunner(logger));
     return logger;
 }
-// --- herdr host (untested: shells out to herdr) ---------------------------
+// --- herdr host (shells out to herdr; injectable via deps.herdr) -----------
 export function parseHerdrJson(output, command) {
     try {
         return JSON.parse(output);
@@ -94,6 +98,14 @@ async function killViaHerdr(label) {
         await exec('herdr', ['workspace', 'close', ws.workspace_id]);
     }
 }
+/** The production host: the real `herdr` binary. */
+export const realHerdrHost = {
+    spawn: spawnViaHerdr,
+    kill: killViaHerdr,
+};
+function herdrHostOf(deps) {
+    return deps.herdr ?? realHerdrHost;
+}
 // --- ls/status freshness ----------------------------------------------------
 const DEFAULT_FRESH_S = 120;
 function freshnessThresholdS(config) {
@@ -102,8 +114,6 @@ function freshnessThresholdS(config) {
         : DEFAULT_FRESH_S;
 }
 function classify(hub, freshS) {
-    // No host probe here (host calls are untested) → can't tell host-missing
-    // from wedged. registry+no-hub = registry-only; stale-hub = wedged.
     if (!hub) {
         return 'registry-only';
     }
@@ -115,7 +125,7 @@ function classify(hub, freshS) {
     return fresh ? 'running' : 'wedged';
 }
 async function buildLsRows(remote, config, onlyId) {
-    const entries = await registry.list();
+    const entries = await listRegisteredConductors();
     let hub = [];
     try {
         hub = await remote.listConductors('me');
@@ -161,9 +171,7 @@ function printRows(rows) {
 // --- command handlers -------------------------------------------------------
 /**
  * Start-time auth gate. Returns true if authenticated (session or session-less
- * provider); otherwise logs a single clear line and returns false. Must run
- * before remote resolution (resolveRemote), which calls resolveAuth and throws
- * when unauthenticated.
+ * provider); otherwise logs a single clear line and returns false.
  */
 export async function ensureAuthenticated(config, logger) {
     const st = await authStatus({
@@ -201,10 +209,6 @@ async function cmdReap(deps, log = {}) {
     const workspace = deps.workspace ?? (await selectWorkspace(config));
     const agents = deps.agents ?? (await selectAgents(config));
     const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
-    // The reaper reconciles finished-but-uncleaned tickets (the cleaned_up flag)
-    // against their worktrees; it needs no registration/heartbeat (it is not a
-    // poll), just the executor + remote, so it runs standalone after a
-    // crash/restart.
     await conductor.reap();
 }
 async function cmdStartForeground(deps, log = {}) {
@@ -232,12 +236,6 @@ async function cmdStartForeground(deps, log = {}) {
     }
 }
 async function cmdStart(deps, log = {}) {
-    // Print the installed version (AC-2) immediately, then kick the newer-version
-    // registry check off CONCURRENTLY with config resolution so a slow/offline
-    // registry never stalls start (finding #1 — the check no longer runs serially
-    // before resolveConfig). Fail-silent + bounded (AC-3/AC-4/AC-5); the notice is
-    // printed once it resolves, after the start work below. Not in
-    // cmdStartForeground — that path is herdr-hosted, no TTY.
     const current = printVersionLine();
     const noticePromise = fetchUpdateNotice(current, deps.fetch ?? globalThis.fetch).catch(() => null);
     try {
@@ -257,7 +255,7 @@ async function cmdStartBody(deps, log) {
         return;
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
-    const existing = await registry.get(id);
+    const existing = await getRegisteredConductor(id);
     if (existing) {
         const hubStatus = await remote.getConductorStatus(id);
         if (hubStatus !== null && hubStatus !== 'offline') {
@@ -266,7 +264,7 @@ async function cmdStartBody(deps, log) {
         }
     }
     const handle = `gaia-conductor:${id}`;
-    await registry.register({
+    await registerConductor({
         id,
         path: checkoutRoot,
         project: config.project,
@@ -274,9 +272,6 @@ async function cmdStartBody(deps, log) {
         host: 'herdr',
         handle,
     });
-    // The detached foreground process is a fresh CLI invocation — forward the
-    // log flags so the herdr-hosted loop logs at the requested level. Sink stays
-    // forced to file (herdr-hosted = no TTY) unless the caller overrode it.
     const fgFlags = [
         log.level ? `--log-level ${log.level}` : '',
         log.sink ? `--log-sink ${log.sink}` : '',
@@ -285,7 +280,7 @@ async function cmdStartBody(deps, log) {
         .join(' ');
     const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground`.replace(/\s+/g, ' ');
     try {
-        await spawnViaHerdr(handle, checkoutRoot, fgCmd);
+        await herdrHostOf(deps).spawn(handle, checkoutRoot, fgCmd);
         logger.info({ id, handle }, 'started conductor via herdr');
     }
     catch (err) {
@@ -298,26 +293,19 @@ async function cmdStop(deps, now) {
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
     if (now) {
-        const entry = await registry.get(id);
+        const entry = await getRegisteredConductor(id);
         if (entry && entry.host === 'herdr') {
-            await killViaHerdr(entry.handle);
+            await herdrHostOf(deps).kill(entry.handle);
             console.log(`hard-stopped conductor ${id} (${entry.handle})`);
         }
         else {
             console.log(`no herdr-hosted conductor to hard-stop for ${id}`);
         }
-        // A hard kill just stops the heartbeat; it never deletes the entity. The
-        // Drupal cron reaper flips the now-stale registration to offline (single
-        // authority for the offline transition — see gaia_core cron).
         return;
     }
-    // Graceful stop: there is no drain phase — the conductor goes offline at once,
-    // just like a hard kill, but writes offline itself instead of waiting for the
-    // cron reaper. Stop the process first (else its next heartbeat would flip it
-    // back online), then mark it offline. In-flight runs are not awaited.
-    const entry = await registry.get(id);
+    const entry = await getRegisteredConductor(id);
     if (entry && entry.host === 'herdr') {
-        await killViaHerdr(entry.handle);
+        await herdrHostOf(deps).kill(entry.handle);
     }
     await remote.setConductorStatus(id, 'offline');
     console.log(`stopped conductor ${id} (offline)`);
@@ -338,7 +326,7 @@ async function cmdStatus(deps) {
 async function cmdRm(deps) {
     const config = await resolveConfig(deps);
     const id = conductorIdOf(config);
-    await registry.remove(id);
+    await removeConductor(id);
     console.log(`removed conductor ${id} from registry`);
 }
 /** ls may run without a config file; best-effort load. */
@@ -347,7 +335,7 @@ async function tryConfig(deps) {
         return deps.config;
     }
     try {
-        return await loadConductorConfig(defaultConfigPath());
+        return await resolveConfig(deps);
     }
     catch {
         return undefined;
@@ -371,7 +359,6 @@ async function promptSecret() {
         output: process.stdout,
         terminal: true,
     });
-    // Mute character echo while the secret is typed.
     rl._writeToOutput = (s) => {
         if (!rl.muted || s.includes('\n'))
             process.stdout.write(s);
@@ -390,60 +377,10 @@ async function promptSecret() {
         rl.close();
     }
 }
-// --- program ----------------------------------------------------------------
-export function buildProgram(deps) {
-    const program = new Command();
-    program
-        .name('gaia')
-        .description('GAIA conductor + client CLI')
-        .option('--conductor <name>', 'select a conductor by stem (conductor→conductor.config.js, else <name>.conductor.config.js; default: conductor.config.js, else the sole config; env $GAIA_CONDUCTOR)');
-    // GAIA-126/137: a repo may hold several .gaia/ conductor configs — the default
-    // conductor.config.js plus <stem>.conductor.config.js variants.
-    // resolveConfigPath already honours $GAIA_CONDUCTOR; thread the global
-    // --conductor flag into it (flag wins over env) so every command selects the
-    // named config without per-command wiring. A per-invocation flag beats any
-    // ambient env for this run.
-    program.hook('preAction', () => {
-        const name = program.opts().conductor;
-        if (typeof name === 'string' && name !== '') {
-            process.env.GAIA_CONDUCTOR = name;
-        }
-    });
-    const cliVersion = resolveCliVersion();
-    program.version(cliVersion); // -V, --version
-    program
-        .command('version')
-        .description('output the gaia CLI version')
-        .action(() => {
-        console.log(cliVersion);
-    });
-    program
-        .command('update')
-        .description('upgrade the globally installed gaia CLI to the latest npm release')
-        .action(async () => {
-        const { ok, before, after } = await runUpdate();
-        if (!ok) {
-            console.error('gaia update failed — see npm output above');
-            process.exitCode = 1;
-            return;
-        }
-        // Report the real on-disk change (finding #2): never a fabricated
-        // "latest", never a false "upgraded" when npm changed nothing.
-        if (after === null) {
-            console.log('gaia update completed (installed version undetermined)');
-        }
-        else if (before === null) {
-            console.log(`gaia installed: ${after}`);
-        }
-        else if (before === after) {
-            console.log(`gaia is already up to date (${after})`);
-        }
-        else {
-            console.log(`gaia updated: ${before} → ${after}`);
-        }
-    });
-    const conductor = program
-        .command('conductor')
+// --- the conductor command tree --------------------------------------------
+/** Build the `conductor` subcommand tree (lifecycle + registry + init). */
+export function createConductorCommand(deps) {
+    const conductor = new Command('conductor')
         .description('node-agent lifecycle + local registry')
         .option('--log-level <level>', 'log verbosity: debug | info | warn | error (overrides GAIA_LOG_LEVEL)')
         .option('--log-sink <sink>', 'log sink: stdout | file (overrides GAIA_CONDUCTOR_LOG)')
@@ -509,36 +446,32 @@ Examples:
         .action(async () => {
         await cmdRm(deps);
     });
+    registerInit(conductor);
+    return conductor;
+}
+/** `gaia conductor init` — scaffold the home machine context + the project's
+ *  split config (connection `gaia.config.js` + engine `conductor.config.js`). */
+function registerInit(conductor) {
     conductor
         .command('init')
-        .description('scaffold the committed .gaia/conductor.config.js for this repo plus the user-global conductor.config.machine.js context (identity + connection incl. secret)')
+        .description('scaffold the project split config (.gaia/gaia.config.js connection + .gaia/conductor.config.js engine) plus the user-global ~/.gaia/machine.config.js context (identity + connection incl. secret)')
         .option('--base-url <url>', 'control-plane base URL (site.base_url) — required only when onboarding this machine')
         .option('--project <name>', 'GAIA project name — required only to scaffold the committed repo config; omit for machine-only onboarding')
         .option('--secret-env <VAR>', 'env var name to read the oauth client secret from (else TTY prompt)')
         .option('--client-id <id>', 'oauth consumer id', 'gaia-agent')
         .option('--machine-id <id>', 'machine host token for the context (defaults to hostname())')
         .option('--user-id <kuerzel>', 'developer Kürzel for the user-global context')
-        .option('--machine-path <path>', 'user-global machine context path (defaults to ~/.config/conductor/conductor.config.machine.js)')
-        .option('--config <path>', 'target committed config path', './.gaia/conductor.config.js')
+        .option('--machine-path <path>', 'user-global machine context path (defaults to ~/.gaia/machine.config.js)')
+        .option('--config <path>', 'target committed engine config path', './.gaia/conductor.config.js')
         .option('--force', 'overwrite an existing committed config', false)
         .option('--reonboard', 'force machine-context onboarding even if a context file exists', false)
         .action(async (opts) => {
-        // Two independent axes decide what init writes:
-        //  - machine axis: an existing context means project-only; --reonboard
-        //    (or an absent context) forces machine-context (re)scaffolding.
-        //  - repo axis: --project scaffolds the committed repo config; omitting
-        //    it means machine-only (no repo). The 4 quadrants:
-        //      context absent  + project → both files
-        //      context absent  + no proj → machine-only onboarding
-        //      context present + project → project-only
-        //      context present + no proj → no-op (machine already onboarded)
         const machinePath = opts.machinePath ?? machineContextPath();
         const existing = await readMachineContext(machinePath);
         const contextPresent = existsSync(machinePath);
         const onboarding = !contextPresent || opts.reonboard;
         const project = opts.project ?? '';
         const hasProject = project.trim() !== '';
-        // Context present and nothing repo-scoped to do → no-op with guidance.
         if (!onboarding && !hasProject) {
             console.log(`machine already onboarded (${machinePath}) — pass --project to set up a repo`);
             return;
@@ -547,7 +480,6 @@ Examples:
         let secret = '';
         const baseUrl = opts.baseUrl ?? '';
         if (onboarding) {
-            // Full onboarding: base-url + user-id + secret are required here.
             if (baseUrl.trim() === '') {
                 throw new Error('--base-url is required when onboarding this machine (no machine context yet, or --reonboard)');
             }
@@ -558,9 +490,6 @@ Examples:
                     throw new Error('--user-id is required (or run in a TTY to be prompted)');
                 }
             }
-            // The secret lives in the machine context; resolve it only when that
-            // context does not already carry one (existing values are never
-            // overwritten). Source: --secret-env value, else a TTY prompt.
             if (typeof existing.client_secret !== 'string' ||
                 existing.client_secret.trim() === '') {
                 secret =
@@ -593,13 +522,17 @@ Examples:
             skipMachine: !onboarding,
             skipCommitted: !hasProject,
         });
-        // Mode banner.
+        // GAIA-218: `conductor init` writes the ENGINE config only. It no longer
+        // scaffolds a project-local `gaia.config.js` — the global
+        // `~/.gaia/gaia.config.js` (seeded by the reachability step below) is the
+        // default connection every repo inherits; a project override is opt-in
+        // via `gaia upgrade`.
         if (!onboarding) {
             console.log(`machine context found (${machinePath}) → setting up project only`);
             if (typeof existing.base_url !== 'string' ||
                 existing.base_url.trim() === '') {
                 console.log(`warning: ${machinePath} exists but looks incomplete (no base_url) — ` +
-                    `run with --reonboard to fill the machine context`);
+                    'run with --reonboard to fill the machine context');
             }
         }
         else if (!hasProject) {
@@ -607,13 +540,29 @@ Examples:
         }
         else {
             console.log(opts.reonboard
-                ? `re-onboarding this machine (--reonboard)`
-                : `no machine context → onboarding this machine`);
+                ? 're-onboarding this machine (--reonboard)'
+                : 'no machine context → onboarding this machine');
         }
         if (hasProject) {
             console.log(res.wroteCommitted
-                ? `wrote ${res.committedPath}`
+                ? `wrote ${res.committedPath} (engine)`
                 : `kept ${res.committedPath} (exists — pass --force to replace)`);
+            // GAIA-216/218: make the split-config seed reachable from `init` itself
+            // — migrate a legacy machine context and seed the HOME connection config
+            // so an install can never be left with an engine config and no
+            // connection config. `projectConnection: 'skip'` keeps `init` from
+            // writing a project override (the global connection is the default;
+            // overrides are opt-in via `gaia upgrade`). Idempotent: a fresh init
+            // reports these as kept. `home` is derived from the machine-context path
+            // (canonical `<home>/.gaia/machine.config.js`) so the home-side steps
+            // target the same home the context lives in.
+            const reach = runUpgrade({
+                cwd: dirname(dirname(opts.config)),
+                home: dirname(dirname(machinePath)),
+                projectConnection: 'skip',
+            });
+            for (const line of reach.actions)
+                console.log(line);
         }
         const m = res.machine;
         if (onboarding) {
@@ -623,93 +572,36 @@ Examples:
                     ? `updated ${m.path} (filled: ${m.filledKeys.join(', ')})`
                     : `kept ${m.path} (already complete)`);
         }
-        console.log(`\nNext steps:\n` +
-            `  gaia dropsh auth login --provider session\n` +
-            `  gaia dropsh auth login --provider pm\n` +
-            `  gaia dropsh auth status   # both profiles present`);
+        console.log('\nNext steps:\n' +
+            '  gaia dropsh auth login --provider session\n' +
+            '  gaia dropsh auth login --provider pm\n' +
+            '  gaia dropsh auth status   # both profiles present');
     });
-    return program;
 }
+/** The `conductor` command plugin the host mounts (GAIA-201). GAIA-224
+ *  (Finding 7): the `gaia deployment` batch helper is no longer registered here —
+ *  it is its own command addon, `@gaia-ai/addon-deployment`. */
+const conductorCommandPlugin = {
+    kind: 'command',
+    name: 'conductor',
+    describe: 'node-agent lifecycle + local registry',
+    register(program, host) {
+        program.addCommand(createConductorCommand({ host }));
+    },
+};
+export default conductorCommandPlugin;
 /**
- * Attach the inherited dropsh CLI as a `gaia dropsh ...` subcommand.
- *
- * When a config is loadable, mounts the dropsh program built with the
- * conductor's plugins (auth providers, etc.). Best-effort: if no config is
- * loadable, the passthrough is simply not mounted.
- *
- * dropsh's own commands (e.g. `auth login`) reload their config from
- * `--config` / `$DROPSH_CONFIG` / the `dropsh.config.js` default — they do not
- * see the conductor config we already loaded. Default `$DROPSH_CONFIG` to the
- * conductor's own config path so `gaia dropsh auth login` uses the same site +
- * plugins without an explicit `--config` flag. An existing `$DROPSH_CONFIG`
- * (or a `--config` flag) still wins.
+ * Build a standalone program with the conductor command mounted — the test entry
+ * (mirrors what the host does for `gaia conductor …`). `deps` inject fakes.
  */
-/** Actionable hint shown when a `gaia dropsh` command runs with no loadable config. */
-function dropshConfigHint(resolvedPath) {
-    return (`gaia dropsh: no conductor config could be loaded (looked at ${resolvedPath}).\n` +
-        `Point at one with --config <path>, set $DROPSH_CONFIG, or run from a directory ` +
-        `containing .gaia/conductor.config.js.`);
-}
-async function attachDropsh(program, deps) {
-    const config = deps.config ?? (await tryConfig(deps));
-    if (config && !process.env.DROPSH_CONFIG) {
-        process.env.DROPSH_CONFIG = config.config_path;
-    }
-    const dropsh = buildDropshProgram({
-        plugins: config?.plugins ?? [],
-    });
-    if (!config) {
-        // Registration is unconditional; a config problem must surface WHEN a dropsh
-        // command runs, not make the command vanish. The hook fires only on a real
-        // subcommand dispatch — never for `--help` — so discoverability holds.
-        dropsh.hook('preSubcommand', async (thisCommand) => {
-            const override = thisCommand.opts().config ??
-                process.env.DROPSH_CONFIG;
-            const resolved = defaultConfigPath(override);
-            let ok = false;
-            try {
-                await loadConductorConfig(resolved);
-                ok = true;
-            }
-            catch {
-                ok = false;
-            }
-            if (!ok) {
-                throw new Error(dropshConfigHint(resolved));
-            }
-            if (!process.env.DROPSH_CONFIG) {
-                process.env.DROPSH_CONFIG = resolved;
-            }
-        });
-    }
-    program.addCommand(dropsh);
-}
-export async function runGaiaCli(argv, deps = {}) {
-    const program = buildProgram(deps);
-    await attachDropsh(program, deps);
-    try {
-        await program.parseAsync(argv, { from: 'user' });
-    }
-    catch (err) {
-        // The mounted dropsh program calls exitOverride(), so commander surfaces
-        // help/errors as a thrown CommanderError instead of exiting the process.
-        // `--help`/`--version` are clean exits; commander-generated errors have
-        // already written their message to stderr, so only report our own thrown
-        // errors (e.g. the dropsh missing-config hint) here.
-        const e = err;
-        if (e.code === 'commander.helpDisplayed' ||
-            e.code === 'commander.version') {
-            return;
-        }
-        if (typeof e.code === 'string' && e.code.startsWith('commander.')) {
-            process.exitCode = process.exitCode ?? 1;
-            return;
-        }
-        process.stderr.write(`${e.message ?? String(err)}\n`);
-        process.exitCode = process.exitCode ?? 1;
-    }
+export function buildConductorProgram(deps = {}) {
+    const program = new Command();
+    program.name('gaia').description('GAIA conductor + client CLI');
+    program.addCommand(createConductorCommand(deps));
+    return program;
 }
-export async function main(argv) {
-    // Drop node + script path; commander parses the rest as user args.
-    await runGaiaCli(argv.slice(2));
+/** Parse argv against the conductor program (test entry). */
+export async function runConductorCli(argv, deps = {}) {
+    const program = buildConductorProgram(deps);
+    await program.parseAsync(argv, { from: 'user' });
 }