@gaia-ai/conductor 0.5.4 → 0.6.0

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

@@ -1,29 +1,36 @@
 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 { CommandRunner, createLogger, exec, loadGaiaConfig, machineContextPath, readMachineContext, resolveConfigPath, setDefaultCommandRunner, } from '@gaia-ai/core';
 import { selectAgents, 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 { authStatus } from 'dropsh';
+import * as conductorRegistry from '../cli/conductor-registry.js';
+import { registerDeployment } from '../cli/deployment.js';
+import { scaffold, scaffoldGaiaConfig } 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';
+/** 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 +40,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;
@@ -102,8 +108,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 +119,7 @@ function classify(hub, freshS) {
     return fresh ? 'running' : 'wedged';
 }
 async function buildLsRows(remote, config, onlyId) {
-    const entries = await registry.list();
+    const entries = await conductorRegistry.list();
     let hub = [];
     try {
         hub = await remote.listConductors('me');
@@ -161,9 +165,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 +203,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 +230,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 +249,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 conductorRegistry.get(id);
     if (existing) {
         const hubStatus = await remote.getConductorStatus(id);
         if (hubStatus !== null && hubStatus !== 'offline') {
@@ -266,7 +258,7 @@ async function cmdStartBody(deps, log) {
         }
     }
     const handle = `gaia-conductor:${id}`;
-    await registry.register({
+    await conductorRegistry.register({
         id,
         path: checkoutRoot,
         project: config.project,
@@ -274,9 +266,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}` : '',
@@ -298,7 +287,7 @@ 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 conductorRegistry.get(id);
         if (entry && entry.host === 'herdr') {
             await killViaHerdr(entry.handle);
             console.log(`hard-stopped conductor ${id} (${entry.handle})`);
@@ -306,16 +295,9 @@ async function cmdStop(deps, now) {
         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 conductorRegistry.get(id);
     if (entry && entry.host === 'herdr') {
         await killViaHerdr(entry.handle);
     }
@@ -338,7 +320,7 @@ async function cmdStatus(deps) {
 async function cmdRm(deps) {
     const config = await resolveConfig(deps);
     const id = conductorIdOf(config);
-    await registry.remove(id);
+    await conductorRegistry.remove(id);
     console.log(`removed conductor ${id} from registry`);
 }
 /** ls may run without a config file; best-effort load. */
@@ -347,7 +329,7 @@ async function tryConfig(deps) {
         return deps.config;
     }
     try {
-        return await loadConductorConfig(defaultConfigPath());
+        return await resolveConfig(deps);
     }
     catch {
         return undefined;
@@ -371,7 +353,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 +371,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 +440,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 +474,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 +484,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 +516,21 @@ Examples:
             skipMachine: !onboarding,
             skipCommitted: !hasProject,
         });
-        // Mode banner.
+        // Scaffold the sibling connection config (project-local gaia.config.js)
+        // next to the engine config when setting up a repo.
+        let wroteConnection = false;
+        let connectionPath = '';
+        if (hasProject) {
+            const conn = scaffoldGaiaConfig(opts.config, opts.force);
+            wroteConnection = conn.wrote;
+            connectionPath = conn.path;
+        }
         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 +538,30 @@ 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)`);
+            console.log(wroteConnection
+                ? `wrote ${connectionPath} (connection)`
+                : `kept ${connectionPath} (exists — pass --force to replace)`);
+            // GAIA-216: 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. 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 — real home in production, isolated
+            // when `--machine-path` overrides it.
+            const reach = runUpgrade({
+                cwd: dirname(dirname(opts.config)),
+                home: dirname(dirname(machinePath)),
+            });
+            for (const line of reach.actions)
+                console.log(line);
         }
         const m = res.machine;
         if (onboarding) {
@@ -623,93 +571,50 @@ 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). It also registers
+ *  the `gaia deployment` batch helper (conductor-scoped: needs remote + project). */
+const conductorCommandPlugin = {
+    kind: 'command',
+    name: 'conductor',
+    describe: 'node-agent lifecycle + local registry',
+    register(program, host) {
+        const deps = { host };
+        program.addCommand(createConductorCommand(deps));
+        registerDeployment(program, async () => {
+            const config = await resolveConfig(deps);
+            return resolveRemote(deps, config);
+        }, async () => {
+            const config = await resolveConfig(deps);
+            return config.project;
+        }, () => process.cwd());
+    },
+};
+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));
+    registerDeployment(program, async () => {
+        const config = await resolveConfig(deps);
+        return resolveRemote(deps, config);
+    }, async () => {
+        const config = await resolveConfig(deps);
+        return config.project;
+    }, () => process.cwd());
+    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' });
 }

package/dist/src/config.d.ts

@@ -1,14 +1,13 @@
-import type { AgentCandidate, ConductorFileConfig } from '@gaia-ai/core';
+import { type AgentCandidate, type ConductorEngineConfig, type ConductorFileConfig, type GaiaConnectionConfig } from '@gaia-ai/core';
+export { findGaiaDir, resolveConfigPath, } from '@gaia-ai/core';
 /**
- * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
+ * Default agent prompt - the project instruction contract. One run works EXACTLY one state;
  * the agent must stop instead of running the whole flow in one session. The run
  * is closed automatically when the ticket state changes on the next claim - the
  * agent does not release it. Run mechanics live here (not in the repo's
- * WORKFLOW.md). The prompt routes through the gaia skill (`ticket:run`) rather
- * than pointing at WORKFLOW.md directly (GAIA-125): the intake line + state
- * engine are a skill mechanic, so a bare "follow WORKFLOW.md" pointer left the
- * intake line unprinted unless an external skill-forcing hook happened to fire. A
- * conductor config may override via the `prompt` field.
+ * WORKFLOW.md). The prompt points directly at the matching project-owned state
+ * section and does not prescribe an agent skill. A conductor config may override
+ * it via the `prompt` field.
  *
  * The ticket + its comments are NOT embedded (GAIA-112): embedding unbounded
  * ticket content into a single typed pane line overran the PTY canonical line
@@ -31,7 +30,7 @@ import type { AgentCandidate, ConductorFileConfig } from '@gaia-ai/core';
  * wrapper, GAIA-118, was the thing that re-inflated the line past the cap and
  * truncated it mid-quote).
  * Placeholders: `{identifier}`, `{state}`, `{runUuid}` ({state} falls back to
- * `triage` for unclassified tickets).
+ * `qualification` for unclassified tickets).
  */
 export declare const DEFAULT_AGENT_PROMPT: string;
 /**
@@ -44,19 +43,47 @@ export declare const DEFAULT_AGENT_PROMPT: string;
  */
 export declare function resolveAgents(raw: unknown, configPath: string): Promise<AgentCandidate | AgentCandidate[]>;
 /**
- * Resolve the conductor config path from `cwd`.
- *
- * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
- * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding a conductor config
- *    — so any subdirectory of a project/worktree resolves the same dir.
- *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves the stem's
- *      file (`conductor` → `conductor.config.js`, else
- *      `<name>.conductor.config.js`; error listing the stems if absent).
- *    - No selector: `conductor.config.js` present → it is the default; else
- *      exactly one config → use it (back-compat); else → error naming the
- *      stems + the selector.
- * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error
- *    (never leak a raw "Cannot find module" from a later import()).
+ * Load the ENGINE half of a conductor config (GAIA-201 split model). Reads
+ * remote/executor/agent/workspace + project/states/machine_id/label/prompt/
+ * scheduler/hooks — and deliberately NOT `site` or the auth `plugins`, which now
+ * live in a `gaia.config.js` connection config. The conductor command composes
+ * the two via `composeConductorConfig`. A legacy `conductor.config.js` still
+ * carrying `site`/`plugins` loads fine — those two keys are simply ignored here
+ * (the connection loader reads them, back-compat).
+ */
+export declare function loadConductorConfig(configFile: string): Promise<ConductorEngineConfig>;
+/**
+ * Compose the full `ConductorFileConfig` the engine consumes from the engine
+ * half (`loadConductorConfig`) and the connection half (`loadGaiaConfig`). The
+ * connection supplies `site` + the auth `plugins`; `ensureAuthenticated` /
+ * `selectRemote` read them exactly as before — the fields just arrive from
+ * `gaia.config.js` now.
+ */
+export declare function composeConductorConfig(engine: ConductorEngineConfig, connection: Pick<GaiaConnectionConfig, 'site' | 'plugins'>): ConductorFileConfig;
+/**
+ * The conductor **stems** in a `.gaia/` dir — the file naming predicate of
+ * GAIA-137: exactly `conductor.config.js` (stem `conductor`) or
+ * `<variant>.conductor.config.js` (stem `<variant>`). The resolution itself
+ * lives in `@gaia-ai/core` (re-exported above); this is the enumeration.
+ */
+export declare function configStems(gaiaDir: string): string[];
+/** Map a conductor stem back to its file name. */
+export declare function fileForStem(stem: string): string;
+/**
+ * List the conductor-config **file names** in a `.gaia/` dir, using the same
+ * naming predicate the loader uses (`configStems`). This is the only supported
+ * enumeration for the `@gaia/upgrade-project` states-strip: it visits the
+ * default `conductor.config.js` + every `<variant>.conductor.config.js`, and
+ * never an unrelated JS config (`vite.config.js`, the near-miss
+ * `myconductor.config.js`).
+ */
+export declare function listConductorConfigFiles(gaiaDir: string): string[];
+/**
+ * Remove the obsolete `states:` array property from a conductor-config JS
+ * source (GAIA-207 made `states` optional — empty ⇒ serve all claimable
+ * states — so `@gaia/upgrade-project` drops the now-dead key). Pure string
+ * transform: it strips the `states: [ ... ]` property (line form or inline in
+ * an object literal) with its trailing comma, and rewrites nothing else. A
+ * `substates:`/other key containing "states" is not matched.
  */
-export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
-export declare function loadConductorConfig(configFile: string): Promise<ConductorFileConfig>;
+export declare function stripStatesFromConfigSource(source: string): string;