@gaia-ai/conductor 0.0.1

package/dist/src/cli/gaia.js

@@ -0,0 +1,690 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { createInterface } from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import { CommandRunner, createLogger, exec, setDefaultCommandRunner, } from '@gaia-ai/core';
+import { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+import { Command } from 'commander';
+import { authStatus, buildProgram as buildDropshProgram } from 'dropsh';
+import { loadConductorConfig, resolveConfigPath } from '../config.js';
+import { Conductor } from '../core/conductor.js';
+import { machineContextPath, readMachineContext, scaffold, } from './init.js';
+import * as registry from './local-registry.js';
+/**
+ * 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).
+ */
+function defaultConfigPath(override) {
+    return resolveConfigPath(override);
+}
+async function resolveConfig(deps, configPathOverride) {
+    if (deps.config) {
+        return deps.config;
+    }
+    return loadConductorConfig(defaultConfigPath(configPathOverride));
+}
+async function resolveRemote(deps, config) {
+    return deps.remote ?? (await selectRemote(config));
+}
+function checkoutRootOf(config) {
+    return dirname(config.config_path);
+}
+/**
+ * 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.
+ */
+function conductorIdOf(config) {
+    const id = config.machine_id;
+    if (id === undefined || id.trim() === '') {
+        throw new Error('conductor config has no machine_id');
+    }
+    return id;
+}
+/** Read the `conductor`-level --log-level / --log-sink flags from a subcommand. */
+function logOptsOf(cmd) {
+    const opts = cmd.optsWithGlobals();
+    return {
+        ...(opts.logLevel !== undefined ? { level: opts.logLevel } : {}),
+        ...(opts.logSink !== undefined ? { sink: opts.logSink } : {}),
+    };
+}
+/** Create the conductor logger (with CLI log overrides) and route all exec logging through it. */
+function loggerFor(checkoutRoot, log = {}) {
+    const logger = createLogger({ checkoutRoot, ...log });
+    setDefaultCommandRunner(new CommandRunner(logger));
+    return logger;
+}
+// --- herdr host (untested: shells out to herdr) ---------------------------
+export function parseHerdrJson(output, command) {
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`herdr ${command} returned invalid JSON`);
+    }
+}
+/** Spawn a detached herdr pane running the given command in cwd. */
+async function spawnViaHerdr(label, cwd, cmd) {
+    const created = await exec('herdr', [
+        'workspace',
+        'create',
+        '--cwd',
+        cwd,
+        '--label',
+        label,
+        '--no-focus',
+    ]);
+    const parsed = parseHerdrJson(created, 'workspace create');
+    const paneId = parsed.result?.root_pane?.pane_id;
+    if (!paneId) {
+        throw new Error('herdr workspace create returned no pane id');
+    }
+    await exec('herdr', ['pane', 'run', paneId, cmd]);
+}
+/** Hard-kill a herdr-hosted conductor by its pane label. */
+async function killViaHerdr(label) {
+    const listed = await exec('herdr', ['workspace', 'list']);
+    const parsed = parseHerdrJson(listed, 'workspace list');
+    const ws = (parsed.result?.workspaces ?? []).find((w) => w.label === label);
+    if (ws?.workspace_id) {
+        await exec('herdr', ['workspace', 'close', ws.workspace_id]);
+    }
+}
+// --- ls/status freshness ----------------------------------------------------
+const DEFAULT_FRESH_S = 120;
+function freshnessThresholdS(config) {
+    return config
+        ? Math.max(DEFAULT_FRESH_S, config.lease_seconds * 2)
+        : 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';
+    }
+    if (hub.status === 'offline') {
+        return 'stopped';
+    }
+    const nowS = Math.floor(Date.now() / 1000);
+    const fresh = hub.lastSeen > 0 && nowS - hub.lastSeen <= freshS;
+    return fresh ? 'running' : 'wedged';
+}
+async function buildLsRows(remote, config, onlyId) {
+    const entries = await registry.list();
+    let hub = [];
+    try {
+        hub = await remote.listConductors('me');
+    }
+    catch {
+        hub = [];
+    }
+    const hubById = new Map(hub.map((c) => [c.id, c]));
+    const freshS = freshnessThresholdS(config);
+    const ids = new Set();
+    for (const e of entries) {
+        ids.add(e.id);
+    }
+    for (const c of hub) {
+        ids.add(c.id);
+    }
+    const rows = [];
+    for (const id of ids) {
+        if (onlyId && id !== onlyId) {
+            continue;
+        }
+        const entry = entries.find((e) => e.id === id);
+        const h = hubById.get(id);
+        rows.push({
+            id,
+            project: entry?.project ?? h?.project ?? '',
+            label: entry?.label ?? h?.label ?? '',
+            host: entry?.host ?? '-',
+            status: classify(h, freshS),
+        });
+    }
+    return rows;
+}
+function printRows(rows) {
+    if (rows.length === 0) {
+        console.log('no conductors registered');
+        return;
+    }
+    for (const r of rows) {
+        console.log(`${r.id}\t${r.status}\t${r.host}\t${r.project}\t${r.label}`);
+    }
+}
+// --- 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.
+ */
+export async function ensureAuthenticated(config, logger) {
+    const st = await authStatus({
+        baseUrl: config.site.base_url,
+        plugins: config.plugins ?? [],
+    });
+    if (!st.loggedIn) {
+        logger.error({ baseUrl: config.site.base_url }, `not logged in against ${config.site.base_url} — run 'gaia dropsh auth login'`);
+        return false;
+    }
+    return true;
+}
+async function cmdPoll(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const agent = deps.agent ?? (await selectAgent(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    await conductor.start();
+    await conductor.tick();
+}
+async function cmdReap(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const agent = deps.agent ?? (await selectAgent(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agent, 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 = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const executor = deps.executor ?? (await selectExecutor(config, logger));
+    const workspace = deps.workspace ?? (await selectWorkspace(config));
+    const agent = deps.agent ?? (await selectAgent(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    await conductor.start();
+    const controller = new AbortController();
+    const onSignal = () => controller.abort();
+    process.once('SIGINT', onSignal);
+    process.once('SIGTERM', onSignal);
+    try {
+        await conductor.serve(controller.signal);
+    }
+    finally {
+        process.removeListener('SIGINT', onSignal);
+        process.removeListener('SIGTERM', onSignal);
+    }
+}
+async function cmdStart(deps, log = {}) {
+    const config = await resolveConfig(deps);
+    const checkoutRoot = checkoutRootOf(config);
+    const logger = loggerFor(checkoutRoot, log);
+    if (!(await ensureAuthenticated(config, logger)))
+        return;
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const existing = await registry.get(id);
+    if (existing) {
+        const hubStatus = await remote.getConductorStatus(id);
+        if (hubStatus !== null && hubStatus !== 'offline') {
+            console.log(`conductor already running for ${config.project}`);
+            return;
+        }
+    }
+    const handle = `gaia-conductor:${id}`;
+    await registry.register({
+        id,
+        path: checkoutRoot,
+        project: config.project,
+        label: config.label,
+        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}` : '',
+    ]
+        .filter(Boolean)
+        .join(' ');
+    const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground`.replace(/\s+/g, ' ');
+    try {
+        await spawnViaHerdr(handle, checkoutRoot, fgCmd);
+        logger.info({ id, handle }, 'started conductor via herdr');
+    }
+    catch (err) {
+        logger.error({ id, err: err.message }, 'could not start via herdr');
+        logger.warn({}, 'Hint: run `gaia conductor start --foreground` under a service manager (systemd-user / docker) on hosts without herdr.');
+    }
+}
+async function cmdStop(deps, now) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    if (now) {
+        const entry = await registry.get(id);
+        if (entry && entry.host === 'herdr') {
+            await killViaHerdr(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);
+    if (entry && entry.host === 'herdr') {
+        await killViaHerdr(entry.handle);
+    }
+    await remote.setConductorStatus(id, 'offline');
+    console.log(`stopped conductor ${id} (offline)`);
+}
+async function cmdLs(deps) {
+    const config = deps.config ?? (await tryConfig(deps));
+    const remote = await resolveRemote(deps, config ?? (await resolveConfig(deps)));
+    const rows = await buildLsRows(remote, config);
+    printRows(rows);
+}
+async function cmdStatus(deps) {
+    const config = await resolveConfig(deps);
+    const remote = await resolveRemote(deps, config);
+    const id = conductorIdOf(config);
+    const rows = await buildLsRows(remote, config, id);
+    printRows(rows);
+}
+async function cmdRm(deps) {
+    const config = await resolveConfig(deps);
+    const id = conductorIdOf(config);
+    await registry.remove(id);
+    console.log(`removed conductor ${id} from registry`);
+}
+/** ls may run without a config file; best-effort load. */
+async function tryConfig(deps) {
+    if (deps.config) {
+        return deps.config;
+    }
+    try {
+        return await loadConductorConfig(defaultConfigPath());
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Prompt for the developer Kürzel / user id on an interactive terminal. */
+async function promptUserId() {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        const answer = await new Promise((resolve) => rl.question('Your Kürzel / user id: ', resolve));
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+/** Prompt for the OAuth client secret without echoing the typed characters. */
+async function promptSecret() {
+    const rl = createInterface({
+        input: process.stdin,
+        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);
+    };
+    try {
+        const answer = await new Promise((resolve) => {
+            rl.question('OAuth client secret: ', (a) => {
+                process.stdout.write('\n');
+                resolve(a);
+            });
+            rl.muted = true;
+        });
+        return answer.trim();
+    }
+    finally {
+        rl.close();
+    }
+}
+// --- program ----------------------------------------------------------------
+// Report the CLI's own package version. Walks up from this module to the
+// nearest @gaia-ai/conductor package.json so it resolves both from the
+// compiled dist/src/cli/gaia.js (3 dirs up) and the src/cli/gaia.ts vitest
+// runs (2 dirs up). Same release tag across packages ⇒ == @gaia-ai/gaia.
+function resolveCliVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (pkg.name === '@gaia-ai/conductor')
+                return pkg.version ?? '0.0.0';
+        }
+        catch {
+            // no package.json here — keep walking up
+        }
+        dir = dirname(dir);
+    }
+    return '0.0.0';
+}
+export function buildProgram(deps) {
+    const program = new Command();
+    program
+        .name('gaia')
+        .description('GAIA conductor + client CLI')
+        .option('--conductor <name>', 'select a named .gaia/<name>.config.js (default: the sole config; env $GAIA_CONDUCTOR)');
+    // GAIA-126: a repo may hold several named .gaia/<stem>.config.js conductors.
+    // 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);
+    });
+    const conductor = program
+        .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)')
+        .addHelpText('after', `
+Logging (precedence: CLI flag > env var > default):
+  --log-level <level>  debug | info (default) | warn | error.
+                       Set debug to see per-poll ticks, claims, and idle cycles.
+  --log-sink <sink>    stdout | file (writes <checkoutRoot>/log.txt).
+                       Default: stdout on a TTY, file otherwise.
+  GAIA_LOG_LEVEL       env fallback for --log-level.
+  GAIA_CONDUCTOR_LOG   env fallback for --log-sink.
+
+Examples:
+  gaia conductor --log-level debug start --foreground
+  gaia conductor --log-level debug poll
+  GAIA_LOG_LEVEL=debug gaia conductor poll`);
+    conductor
+        .command('start')
+        .description('start the conductor loop (herdr-hosted by default)')
+        .option('--foreground', 'run the loop in this process', false)
+        .action(async function (opts) {
+        if (opts.foreground) {
+            await cmdStartForeground(deps, logOptsOf(this));
+        }
+        else {
+            await cmdStart(deps, logOptsOf(this));
+        }
+    });
+    conductor
+        .command('poll')
+        .description('run one conductor cycle then exit')
+        .action(async function () {
+        await cmdPoll(deps, logOptsOf(this));
+    });
+    conductor
+        .command('reap')
+        .description('tear down herdr worktrees of finished-but-uncleaned tickets (recovers orphans a live tick missed: conductor was down at done, restarted, or reassigned)')
+        .action(async function () {
+        await cmdReap(deps, logOptsOf(this));
+    });
+    conductor
+        .command('stop')
+        .description('stop the conductor: graceful offline (default) or hard kill (--now)')
+        .option('--now', 'hard-kill via host and let the cron reaper mark it offline', false)
+        .action(async (opts) => {
+        await cmdStop(deps, opts.now);
+    });
+    conductor
+        .command('ls')
+        .description('list conductors on this machine + status')
+        .action(async () => {
+        await cmdLs(deps);
+    });
+    conductor
+        .command('status')
+        .description('status of the conductor for this checkout')
+        .action(async () => {
+        await cmdStatus(deps);
+    });
+    conductor
+        .command('rm')
+        .description('deregister the conductor for this checkout')
+        .action(async () => {
+        await cmdRm(deps);
+    });
+    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)')
+        .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('--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;
+        }
+        let userId = opts.userId ?? '';
+        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)');
+            }
+            if (userId.trim() === '') {
+                if (process.stdin.isTTY)
+                    userId = await promptUserId();
+                if (userId.trim() === '') {
+                    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 =
+                    opts.secretEnv !== undefined
+                        ? (process.env[opts.secretEnv] ?? '')
+                        : '';
+                if (secret.trim() === '') {
+                    if (process.stdin.isTTY)
+                        secret = await promptSecret();
+                    if (secret.trim() === '') {
+                        throw new Error('OAuth client secret required: pass --secret-env <VAR> (exported) or run in a TTY to be prompted');
+                    }
+                }
+            }
+        }
+        const inputs = {
+            baseUrl,
+            project,
+            clientId: opts.clientId,
+            secret,
+            userId,
+            ...(opts.machineId !== undefined
+                ? { machineId: opts.machineId }
+                : {}),
+        };
+        const res = await scaffold(inputs, {
+            configPath: opts.config,
+            force: opts.force,
+            machinePath,
+            skipMachine: !onboarding,
+            skipCommitted: !hasProject,
+        });
+        // Mode banner.
+        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`);
+            }
+        }
+        else if (!hasProject) {
+            console.log(`onboarding this machine (no project) → run again with --project inside a repo to set it up`);
+        }
+        else {
+            console.log(opts.reonboard
+                ? `re-onboarding this machine (--reonboard)`
+                : `no machine context → onboarding this machine`);
+        }
+        if (hasProject) {
+            console.log(res.wroteCommitted
+                ? `wrote ${res.committedPath}`
+                : `kept ${res.committedPath} (exists — pass --force to replace)`);
+        }
+        const m = res.machine;
+        if (onboarding) {
+            console.log(m.created
+                ? `wrote ${m.path} (user-global machine context)`
+                : m.filledKeys.length > 0
+                    ? `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`);
+    });
+    return program;
+}
+/**
+ * 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.
+ */
+/** 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 async function main(argv) {
+    // Drop node + script path; commander parses the rest as user args.
+    await runGaiaCli(argv.slice(2));
+}