@bakers-build/conductor 0.0.0-stage → 0.1.0-next.42

package/dist/src/config.js

@@ -0,0 +1,712 @@
+import { readdirSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { discoverAddons, discoverScoped, findDefaultExportObject, machineContextPath, matchDelimiter, readMachineContext, resolveConductorSlots, resolveModuleEslintStyle, scanTopLevelProperties, scopeAddons, } from '@bakers-build/core';
+import { readBbProjectSelection } from './cli/project-context.js';
+import { loadInbox } from './plugins/message.js';
+import { narrowConductorContributions, } from './plugins/preset.js';
+// BB-201: the `.bakers/` walk-up + connection resolution moved to `@bakers-build/core`
+// (`resolveConfigPath` / `resolveBbConfigPath` / `findBbDir`). Re-export the
+// engine resolver here so existing conductor callers/tests keep importing it
+// from `../config.js`.
+export { findBbDir, resolveConfigPath, } from '@bakers-build/core';
+/**
+ * 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 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 (BB-112): embedding unbounded
+ * ticket content into a single typed pane line overran the PTY canonical line
+ * cap and truncated the dispatch command. Instead the prompt is a bounded,
+ * constant-size pointer and the agent reads the ticket + all comments at run
+ * start via `bakers dropsh read … --include comments`.
+ *
+ * herdr no longer types this into the pane: the launch command goes to a file
+ * that a short `sh '<file>'` line runs (BB-635), so its length is not bound
+ * by the tty canonical cap (macOS 1024 B, Linux 4096 B). The prompt is still
+ * kept single-line (BB-128 test).
+ * Placeholders: `{identifier}`, `{state}`, `{runUuid}` ({state} falls back to
+ * `qualification` for unclassified tickets).
+ *
+ * WHERE THE PROMPT SENDS THE AGENT, and why it no longer names a WORKFLOW.md
+ * section. This used to say `execute only its ordered "State: {state}" section`,
+ * which described the pre-BB-204 loader: WORKFLOW.md then carried one ordered
+ * `## State: <state>` section per state. BB-204 replaced that with a pure
+ * loader — WORKFLOW.md lists skills, each skill self-declares the
+ * `(work_type, workflow, step)` triple it owns, and the step's flow lives in the
+ * skill. No project's WORKFLOW.md has carried a `State:` section since.
+ *
+ * The prompt kept pointing at one anyway, and that is not cosmetic: a dispatched
+ * agent that reads the instruction literally finds no such section and STOPS.
+ * Observed on a fixture run — "WORKFLOW.md has no ordered State: spec section;
+ * it instead declares skill-based routing. Stopped at this configuration
+ * mismatch." Agents that completed runs were working around the prompt rather
+ * than following it, which is why this survived so long: it failed silently and
+ * only against the most literal readers.
+ */
+export const DEFAULT_AGENT_PROMPT = `You are working ticket {identifier}, current state: {state}. Read the ticket and all comments ` +
+    `(bakers dropsh --format md read bb_ticket/bb_ticket/$BB_ID --include comments), ` +
+    `then read ./WORKFLOW.md, load the bakers.build skill its loader names for this ticket's work type ` +
+    `and state, and execute only that skill's {state} section. ` +
+    `Do not start or prepare a later state.`;
+const HOOK_SLOTS = [
+    'after_create',
+    'before_run',
+    'after_run',
+    'after_done',
+    'on_freeze',
+    'on_resume',
+];
+/**
+ * Loads every addon's contract-2 inbox messages; one that fails validation
+ * is reported and left out, so a broken addon never stops the conductor.
+ */
+async function loadInboxAddons(found) {
+    const loaded = [];
+    for (const addon of found) {
+        try {
+            loaded.push(await loadInbox(addon, addon.options));
+        }
+        catch (err) {
+            console.error(`addon inbox skipped: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    return loaded;
+}
+/**
+ * Validate the `hooks` accumulator result (BB-599). A malformed declaration
+ * is a config error, raised before anything is dispatched; a valid callback
+ * that later fails is best effort and handled by the conductor.
+ */
+function validateHookListeners(value) {
+    if (!Array.isArray(value))
+        throw new Error('conductor addons[] hooks must accumulate an array');
+    for (const [index, listener] of value.entries()) {
+        if (!isRecord(listener))
+            throw new Error(`hooks[${index}] must be a listener object`);
+        for (const slot of HOOK_SLOTS) {
+            if (listener[slot] !== undefined && typeof listener[slot] !== 'function')
+                throw new Error(`hooks[${index}].${slot} must be a function`);
+        }
+        if (listener.id !== undefined && typeof listener.id !== 'string')
+            throw new Error(`hooks[${index}].id must be a string`);
+    }
+    return value;
+}
+function validateProcessHost(value) {
+    if (!Array.isArray(value) || value.length === 0)
+        return undefined;
+    const host = value[value.length - 1];
+    if (!isRecord(host) || typeof host.spawn !== 'function') {
+        throw new Error('conductor addons[] processHosts must accumulate a host with spawn()');
+    }
+    return host;
+}
+function requirePlugin(value, kind) {
+    if (!isRecord(value) || value.kind !== kind) {
+        throw new Error(`conductor config requires a ${kind} plugin in the "${kind}" slot`);
+    }
+    return value;
+}
+/**
+ * A named-plugin descriptor `{ plugin, export?, with?/options? }` — the
+ * import-free form. `config.ts` resolves it into a constructed plugin, so a
+ * committed conductor.config.js need not `import` its plugin packages (which
+ * would resolve relative to the config file, not the CLI — the source of the
+ * "unknown command dropsh" breakage after the @bakers → @bakers-ai scope rename).
+ * Mirror of dropsh 0.4.1 `loadNamedPlugin` / `resolveSlot`.
+ */
+function isPluginDescriptor(entry) {
+    return isRecord(entry) && typeof entry.plugin === 'string';
+}
+/**
+ * Resolve + construct a descriptor. Resolution base order, ESLint-style:
+ * config dir → cwd → conductor install (`import.meta.url`) — the first
+ * `createRequire(base).resolve(name)` that succeeds wins. Then `import` the
+ * module, pick `export` (default 'default'), and call the factory with
+ * `with` (falling back to `options`).
+ */
+async function loadNamedPlugin(entry, configPath) {
+    const bases = [
+        pathToFileURL(configPath).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    const resolved = resolveModuleEslintStyle(entry.plugin, bases);
+    if (resolved === undefined) {
+        throw new Error(`conductor config cannot resolve plugin '${entry.plugin}'`);
+    }
+    const mod = (await import(pathToFileURL(resolved).href));
+    let factory;
+    if (typeof entry.export === 'string') {
+        factory = mod[entry.export];
+        if (typeof factory !== 'function') {
+            throw new Error(`plugin '${entry.plugin}' has no callable export '${entry.export}'`);
+        }
+    }
+    else if (typeof mod.default === 'function') {
+        factory = mod.default;
+    }
+    else {
+        const fns = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+        if (fns.length === 1) {
+            factory = mod[fns[0]];
+        }
+        else {
+            throw new Error(`plugin '${entry.plugin}' has no default export and ${fns.length} function exports (${fns.join(', ')}); specify "export"`);
+        }
+    }
+    return factory(entry.with ?? entry.options);
+}
+/**
+ * Resolve a slot value: a descriptor is constructed via `loadNamedPlugin`, an
+ * already-constructed plugin passes straight through (backward-compat). Either
+ * way the kind-guard runs, so a wrong-target descriptor still errors.
+ */
+async function resolveSlot(value, kind, configPath) {
+    const resolved = isPluginDescriptor(value)
+        ? await loadNamedPlugin(value, configPath)
+        : value;
+    return requirePlugin(resolved, kind);
+}
+/**
+ * Resolve the `agent` slot into candidate(s), **preserving the authored shape**:
+ * a single descriptor/plugin/wrapper → a single `AgentCandidate`, an array →
+ * `AgentCandidate[]`. Each entry is either a bare descriptor/plugin or a
+ * `{ agent, priority? }` wrapper; the inner agent value is resolved through the
+ * same `agent` kind-guard as any slot, and a `priority` function is preserved
+ * verbatim (AC-1, AC-2). Normalization to a list happens at selection time.
+ */
+export async function resolveAgents(raw, configPath) {
+    const resolveOne = async (entry) => {
+        const hasWrapper = isRecord(entry) &&
+            'agent' in entry &&
+            !('kind' in entry) &&
+            !('plugin' in entry);
+        const agentValue = hasWrapper ? entry.agent : entry;
+        const priority = hasWrapper
+            ? entry.priority
+            : undefined;
+        const agent = await resolveSlot(agentValue, 'agent', configPath);
+        return {
+            agent,
+            ...(priority ? { priority } : {}),
+            ...(hasWrapper && typeof entry.alias === 'string'
+                ? { alias: entry.alias }
+                : {}),
+            ...(hasWrapper && typeof entry.description === 'string'
+                ? { description: entry.description }
+                : {}),
+            ...(hasWrapper && typeof entry.model === 'string'
+                ? { model: entry.model }
+                : {}),
+            ...(hasWrapper && typeof entry.modelVersion === 'string'
+                ? { modelVersion: entry.modelVersion }
+                : {}),
+        };
+    };
+    return Array.isArray(raw)
+        ? Promise.all(raw.map(resolveOne))
+        : resolveOne(raw);
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(value, key) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`conductor config requires non-empty ${key}`);
+    }
+    return value;
+}
+function optionalPositiveInteger(value, fallback, key) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`conductor config requires positive integer ${key}`);
+    }
+    return value;
+}
+/**
+ * Load the ENGINE half of a conductor config (BB-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 `bakers.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 async function loadConductorConfig(configFile) {
+    const configPath = resolve(configFile);
+    const bakers = readBbProjectSelection(configPath);
+    const module = (await import(pathToFileURL(configPath).href));
+    const raw = module.default;
+    if (!isRecord(raw)) {
+        throw new Error('conductor config default export must be an object');
+    }
+    // BB-218 (AC-6): the engine config must not carry connection/auth material.
+    // A legacy config still declaring `site`/`plugins` gets exactly ONE actionable
+    // warning naming the file + the offending key(s); the values are never merged
+    // (`ConductorEngineConfig` omits both structurally).
+    const leftover = ['site', 'plugins'].filter((k) => k in raw);
+    if (leftover.length > 0) {
+        console.warn(`warning: ${configPath} declares ${leftover.join('/')} — ignored; ` +
+            'auth/connection belong in the sibling bakers.config.js (BB-218)');
+    }
+    const config = raw;
+    const retiredAgentKeys = [
+        'agent',
+        'agents',
+        'default_agent',
+        'agent_routes',
+    ].filter((key) => key in raw);
+    if (retiredAgentKeys.length > 0) {
+        throw new Error(`${configPath}: retired conductor agent policy ${retiredAgentKeys.join(', ')}; run bakers config upgrade --scope all`);
+    }
+    const project = bakers.project;
+    // `states` is optional. An empty (or absent) list means the conductor serves
+    // every claimable state in its project; a non-empty list narrows it to those
+    // states (BB-207). When present it must be an array of non-empty strings.
+    const states = Array.isArray(config.states)
+        ? config.states.map((state) => requireNonEmptyString(state, 'states'))
+        : [];
+    // conductor_id is required (BB-353 renamed from machine_id). Prefer the new
+    // key; accept legacy machine_id with a one-shot warning. No derived fallback.
+    // A repo's committed config composes it from the machine context
+    // (`${user_id}-${host}-${project}`); co-located configs each compose their
+    // own from their project.
+    let conductorId;
+    if (typeof config.conductor_id === 'string' &&
+        config.conductor_id.trim() !== '') {
+        conductorId = config.conductor_id.trim();
+    }
+    else if (typeof config.machine_id === 'string' &&
+        config.machine_id.trim() !== '') {
+        console.warn(`[bakers] ${configPath}: engine key "machine_id" is deprecated; use "conductor_id" (BB-353)`);
+        conductorId = config.machine_id.trim();
+    }
+    else {
+        throw new Error(`conductor config requires non-empty conductor_id (legacy machine_id accepted)`);
+    }
+    const label = typeof config.label === 'string' && config.label.trim() !== ''
+        ? config.label
+        : conductorId;
+    // Host capacity has one owner. Stale engine values need an explicit migration.
+    if (config.max_parallel !== undefined) {
+        throw new Error(`${configPath}: misplaced max_parallel belongs in ${machineContextPath()}; run bakers config upgrade --scope all`);
+    }
+    const machineCtx = await readMachineContext();
+    const maxParallel = typeof machineCtx.max_parallel === 'number' &&
+        Number.isFinite(machineCtx.max_parallel) &&
+        machineCtx.max_parallel >= 1
+        ? Math.floor(machineCtx.max_parallel)
+        : 1;
+    const tunnel = machineCtx.tunnel === true;
+    // Host stem for bb_machine / registration (BB-353) — prefer the machine
+    // context id over hyphen-splitting the composed conductor_id.
+    const hostKey = typeof machineCtx.machine_id === 'string' &&
+        machineCtx.machine_id.trim() !== ''
+        ? machineCtx.machine_id.trim()
+        : undefined;
+    // BB-215: discover the conductor `addons: []` surface (last-wins singletons,
+    // agent candidate list). A pre-existing per-slot descriptor still loads and
+    // WINS over a discovered contributor of the same kind (back-compat additive).
+    // BB-224: `discoverAddons` is surface-AGNOSTIC — it returns opaque
+    // accumulators. This is the single, reviewed narrowing seam where the engine
+    // reinterprets them as its own concrete conductor contributions; the runtime
+    // `.kind` guard inside `resolveConductorSlots` still fails loudly on a
+    // mis-declared contribution.
+    // The machine and this project config each carry one `addons[]`, read the
+    // same way: each addon declares the scopes it may be listed in, and the
+    // machine entry wins (`scopeAddons`). Agents come from this list too.
+    const policy = machineCtx.agents;
+    if (policy !== undefined && !isRecord(policy))
+        throw new Error('machine agents must be an object');
+    if (policy?.addons !== undefined)
+        throw new Error('machine agents.addons is retired: move its entries into machine.config.js addons[] (run bakers config upgrade --scope machine)');
+    const machineAddons = machineCtx.addons ?? [];
+    if (!Array.isArray(machineAddons))
+        throw new Error('machine addons must be an array');
+    const addonEntries = Array.isArray(config.addons)
+        ? config.addons
+        : [];
+    const addonBases = [
+        pathToFileURL(configPath).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    const machineBases = [
+        pathToFileURL(machineContextPath()).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    const { addons: effectiveAddons } = await scopeAddons([
+        {
+            scope: 'machine',
+            path: machineContextPath(),
+            entries: machineAddons,
+            bases: machineBases,
+        },
+        {
+            scope: 'project',
+            path: configPath,
+            entries: addonEntries,
+            bases: addonBases,
+        },
+    ]);
+    const discovered = narrowConductorContributions(await discoverScoped(effectiveAddons, 'conductor'));
+    const wired = resolveConductorSlots(discovered);
+    const hookListeners = validateHookListeners(discovered.hooks);
+    const inboxAddons = await loadInboxAddons(discovered.addonInbox);
+    // Explicit executor/workspace descriptors still load those slots, but they
+    // skip addons[] discovery — so a pre-BB-215 config never contributes a
+    // process host unless we load that package's processHosts accumulator too.
+    let processHost = validateProcessHost(discovered.processHosts);
+    if (processHost === undefined) {
+        const slotPlugins = [
+            ...new Set([config.executor, config.workspace]
+                .filter(isPluginDescriptor)
+                .map((entry) => entry.plugin)),
+        ];
+        for (const spec of slotPlugins) {
+            // A descriptor may be a plain factory file (`./fixture.js`), not an
+            // addon preset. Slot resolution owns that error; skip a host we cannot
+            // discover and keep looking at the other slot.
+            try {
+                const found = validateProcessHost(narrowConductorContributions(await discoverAddons([spec], 'conductor', addonBases, {
+                    only: ['processHosts'],
+                })).processHosts);
+                if (found !== undefined)
+                    processHost = found;
+            }
+            catch {
+                // no process host from this descriptor
+            }
+        }
+    }
+    const remote = config.remote !== undefined
+        ? await resolveSlot(config.remote, 'remote', configPath)
+        : wired.remote;
+    if (!remote) {
+        throw new Error('conductor config resolves no remote — name a remote addon in addons[] or set the remote slot');
+    }
+    const executor = config.executor !== undefined
+        ? await resolveSlot(config.executor, 'executor', configPath)
+        : wired.executor;
+    if (!executor) {
+        throw new Error('conductor config resolves no executor — name an executor addon in addons[] or set the executor slot');
+    }
+    const workspace = config.workspace !== undefined
+        ? await resolveSlot(config.workspace, 'workspace', configPath)
+        : wired.workspace;
+    if (!workspace) {
+        throw new Error('conductor config resolves no workspace — name a workspace addon in addons[] or set the workspace slot');
+    }
+    const installedHarnesses = new Set(machineAddons.flatMap((entry) => {
+        if (typeof entry === 'string')
+            return [entry];
+        if (!isRecord(entry))
+            return [];
+        const packageName = entry.use ?? entry.name;
+        return typeof packageName === 'string' ? [packageName] : [];
+    }));
+    const dedupeCandidates = (candidates) => {
+        const last = new Map(candidates.map((candidate, index) => [candidate.alias, index]));
+        return candidates.filter((candidate, index) => candidate.alias === undefined || last.get(candidate.alias) === index);
+    };
+    let candidates = dedupeCandidates(wired.agents);
+    const catalog = policy?.catalog;
+    if (catalog !== undefined && !Array.isArray(catalog))
+        throw new Error('agents.catalog must be an array');
+    for (const [index, entry] of (catalog ?? []).entries()) {
+        if (!isRecord(entry) || typeof entry.harness !== 'string')
+            throw new Error(`agents.catalog[${index}] requires a non-empty harness`);
+        const harness = entry.harness.trim();
+        if (!harness || !installedHarnesses.has(harness))
+            throw new Error(`agents.catalog[${index}] harness '${entry.harness}' must also appear in machine.config.js addons[]`);
+        if (entry.alias !== undefined &&
+            (typeof entry.alias !== 'string' || !entry.alias.trim()))
+            throw new Error(`agents.catalog[${index}].alias must be non-empty`);
+        const contribution = narrowConductorContributions(await discoverAddons([
+            {
+                use: harness,
+                ...(entry.with !== undefined ? { with: entry.with } : {}),
+            },
+        ], 'conductor', machineBases, { only: ['agents'] })).agents;
+        const alias = typeof entry.alias === 'string' ? entry.alias.trim() : undefined;
+        if (!alias && contribution.length > 1)
+            throw new Error(`agents.catalog[${index}] harness '${harness}' publishes multiple candidates; name an alias`);
+        const selected = alias
+            ? (contribution.find((candidate) => candidate.alias === alias) ??
+                (contribution.length === 1 ? contribution[0] : undefined))
+            : contribution[0];
+        if (!selected)
+            throw new Error(`agents.catalog[${index}] cannot select one candidate from '${harness}'`);
+        const overlaid = alias ? { ...selected, alias } : selected;
+        if (!overlaid.alias)
+            throw new Error(`agents.catalog[${index}] resolves a candidate without an alias`);
+        const existing = candidates.findIndex((candidate) => candidate.alias === overlaid.alias);
+        if (existing >= 0)
+            candidates[existing] = overlaid;
+        else
+            candidates.push(overlaid);
+    }
+    candidates = candidates.map((candidate) => ({
+        ...candidate,
+        alias: typeof candidate.alias === 'string' && candidate.alias.trim() !== ''
+            ? candidate.alias
+            : candidate.agent.id,
+    }));
+    if (candidates.length === 0)
+        throw new Error('machine.config.js addons[] must resolve a non-empty catalog of aliased agents');
+    const declaredAliases = candidates.map((candidate) => candidate.alias);
+    const readAliasList = (key) => {
+        const value = policy?.[key];
+        if (value === undefined)
+            return [];
+        if (!Array.isArray(value) ||
+            value.some((alias) => typeof alias !== 'string' || !alias.trim()))
+            throw new Error(`agents.${key} must be an array of non-empty aliases`);
+        const aliases = value.map((alias) => alias.trim());
+        const unknown = aliases.find((alias) => !declaredAliases.includes(alias));
+        if (unknown)
+            throw new Error(`agents.${key} names unknown alias '${unknown}'`);
+        return [...new Set(aliases)];
+    };
+    const enabled = readAliasList('enabled');
+    const disabled = readAliasList('disabled');
+    const allowed = policy?.enabled === undefined ? null : new Set(enabled);
+    const denied = new Set(disabled);
+    candidates = candidates.filter((candidate) => (!allowed || allowed.has(candidate.alias)) &&
+        !denied.has(candidate.alias));
+    if (candidates.length === 0)
+        throw new Error('effective agent catalog is empty after agents filters');
+    const enabledAgents = [
+        ...new Set(candidates.map((candidate) => candidate.alias)),
+    ];
+    const configuredDefault = policy?.default_agent;
+    if (configuredDefault !== undefined &&
+        (typeof configuredDefault !== 'string' || !configuredDefault.trim()))
+        throw new Error('agents.default_agent must be a non-empty alias');
+    const defaultAgent = typeof configuredDefault === 'string'
+        ? configuredDefault.trim()
+        : enabledAgents[0];
+    if (!enabledAgents.includes(defaultAgent))
+        throw new Error(`agents.default_agent names unavailable alias '${defaultAgent}'`);
+    const rawRoutes = policy?.routes;
+    if (rawRoutes !== undefined && !isRecord(rawRoutes))
+        throw new Error('agents.routes must be an object of named routes');
+    const routes = {};
+    for (const [name, route] of Object.entries(rawRoutes ?? {})) {
+        if (!name.trim() ||
+            !isRecord(route) ||
+            Object.keys(route).length === 0 ||
+            Object.keys(route).some((state) => !state.trim()) ||
+            Object.values(route).some((alias) => typeof alias !== 'string' || !alias.trim()))
+            throw new Error(`agents.routes.${name || '<empty>'} must map states (or *) to non-empty aliases`);
+        routes[name] = { ...route };
+    }
+    if (!routes.default)
+        routes.default = { '*': defaultAgent };
+    if (config.selectAgent !== undefined &&
+        typeof config.selectAgent !== 'function') {
+        throw new Error('selectAgent must be a function');
+    }
+    return {
+        remote,
+        executor,
+        agents: candidates,
+        enabled_agents: enabledAgents,
+        disabled_agents: disabled,
+        default_agent: defaultAgent,
+        routes,
+        ...(typeof config.selectAgent === 'function'
+            ? {
+                selectAgent: config.selectAgent,
+            }
+            : {}),
+        workspace,
+        hookListeners,
+        ...(inboxAddons.length > 0 ? { inboxAddons } : {}),
+        ...(processHost !== undefined ? { processHost } : {}),
+        bakers,
+        label,
+        conductor_id: conductorId,
+        // Soft alias so callers that still read machine_id keep working this cut.
+        machine_id: conductorId,
+        project,
+        states,
+        prompt: typeof config.prompt === 'string' && config.prompt.trim() !== ''
+            ? config.prompt
+            : DEFAULT_AGENT_PROMPT,
+        max_parallel: maxParallel,
+        tunnel,
+        ...(hostKey !== undefined ? { host_key: hostKey } : {}),
+        poll_interval_ms: optionalPositiveInteger(config.poll_interval_ms, 5000, 'poll_interval_ms'),
+        lease_seconds: optionalPositiveInteger(config.lease_seconds, 300, 'lease_seconds'),
+        ...(config.hooks !== undefined ? { hooks: config.hooks } : {}),
+        config_path: configPath,
+    };
+}
+/**
+ * Compose the full `ConductorFileConfig` the engine consumes from the engine
+ * half (`loadConductorConfig`) and the connection half (`loadBbConfig`). The
+ * connection supplies `site` + the auth `plugins`; `ensureAuthenticated` /
+ * `selectRemote` read them exactly as before — the fields just arrive from
+ * `bakers.config.js` now.
+ */
+export function composeConductorConfig(engine, connection) {
+    return {
+        ...engine,
+        site: connection.site,
+        ...(connection.plugins.length > 0 ? { plugins: connection.plugins } : {}),
+    };
+}
+const DEFAULT_CONFIG = 'conductor.config.js';
+const VARIANT_SUFFIX = '.conductor.config.js';
+/**
+ * The conductor **stems** in a `.bakers/` dir — the file naming predicate of
+ * BB-137: exactly `conductor.config.js` (stem `conductor`) or
+ * `<variant>.conductor.config.js` (stem `<variant>`). The resolution itself
+ * lives in `@bakers-build/core` (re-exported above); this is the enumeration.
+ */
+export function configStems(bakersDir) {
+    return readdirSync(bakersDir)
+        .map((f) => f === DEFAULT_CONFIG
+        ? 'conductor'
+        : f.endsWith(VARIANT_SUFFIX)
+            ? f.slice(0, -VARIANT_SUFFIX.length)
+            : undefined)
+        .filter((s) => s !== undefined)
+        .sort();
+}
+/** Map a conductor stem back to its file name. */
+export function fileForStem(stem) {
+    return stem === 'conductor' ? DEFAULT_CONFIG : `${stem}${VARIANT_SUFFIX}`;
+}
+/**
+ * List the conductor-config **file names** in a `.bakers/` dir, using the same
+ * naming predicate the loader uses (`configStems`). This is the only supported
+ * enumeration for the `@bakers-build/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 function listConductorConfigFiles(bakersDir) {
+    return configStems(bakersDir).map(fileForStem);
+}
+/**
+ * Remove the obsolete `states:` array property from a conductor-config JS
+ * source (BB-207 made `states` optional — empty ⇒ serve all claimable
+ * states — so `@bakers-build/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 function stripStatesFromConfigSource(source) {
+    return source.replace(/\n?[ \t]*(?<![A-Za-z0-9_$])states[ \t]*:[ \t]*\[[^\]]*\][ \t]*,?/g, '');
+}
+// ---------------------------------------------------------------------------
+// BB-218 (AC-7): strip legacy connection/auth from an ENGINE config source.
+//
+// Unlike `stripStatesFromConfigSource`'s flat `\[[^\]]*\]` regex (nested-unsafe),
+// this is a balanced-delimiter, comment-aware source transform. The engine
+// config's `plugins: [ … ]` array holds nested `{}` (oauth2 profiles AND
+// `@bakers-build/addon-essentials`), a sibling `agent: [ … ]` array, and the word
+// "plugins" also appears in comments — so the removal keys on the REAL `site:` /
+// `plugins:` *properties* of the default-export object, scanning each value from
+// its opening delimiter to the matching close while skipping string/comment
+// bytes. It also removes the now-orphaned connection preamble consts
+// (`baseUrl`/`clientId`/`clientSecret`) and a connection-only `loadMachine`
+// (with its `const machine = await loadMachine()`) when they become unreferenced.
+// ---------------------------------------------------------------------------
+// BB-230: the scanner primitives themselves now live in `@bakers-build/core`
+// (`core/src/cli/config-source.ts`) — the kernel needs them for the content-gated
+// legacy connection read, and layer 0 cannot import this package. Imported above.
+/** Count word-boundary occurrences of an identifier in the source. */
+function countIdent(src, name) {
+    const re = new RegExp(`(?<![A-Za-z0-9_$])${name}(?![A-Za-z0-9_$])`, 'g');
+    return (src.match(re) ?? []).length;
+}
+/** Remove a single-line `const <name> = …;` declaration (no-op if absent). */
+function removeConstDecl(src, name) {
+    const re = new RegExp(`^[ \\t]*const ${name}\\b[^\\n]*\\n`, 'm');
+    return src.replace(re, '');
+}
+/** Remove an `[async ]function <name>(…) { … }` declaration (balanced body). */
+function removeFunctionDecl(src, name) {
+    const re = new RegExp(`(?:async[ \\t]+)?function[ \\t]+${name}[ \\t]*\\(`);
+    const m = re.exec(src);
+    if (!m)
+        return src;
+    const braceIdx = src.indexOf('{', m.index);
+    if (braceIdx === -1)
+        return src;
+    const end = matchDelimiter(src, braceIdx);
+    if (end === -1)
+        return src;
+    let e = end + 1;
+    if (src[e] === '\n')
+        e++;
+    return src.slice(0, m.index) + src.slice(e);
+}
+/**
+ * Is `machine` referenced anywhere OTHER than its own `const machine = …;` decl
+ * and inside the `loadMachine` function body? (The body's `…/machine.config.js`
+ * path string must not count as a live reference.) Used to decide whether a
+ * connection-only `loadMachine` has become orphaned.
+ */
+function machineReferencedElsewhere(src) {
+    let probe = removeFunctionDecl(src, 'loadMachine');
+    probe = removeConstDecl(probe, 'machine');
+    return countIdent(probe, 'machine') > 0;
+}
+/** Drop connection preamble that is orphaned once `site`/`plugins` are gone. */
+function removeOrphanedPreamble(src) {
+    let text = src;
+    for (const name of ['baseUrl', 'clientId', 'clientSecret']) {
+        if (countIdent(text, name) <= 1)
+            text = removeConstDecl(text, name);
+    }
+    // A connection-only `loadMachine`: remove `const machine = await loadMachine()`
+    // + the function itself only when `machine` is otherwise unreferenced (so an
+    // engine config that still composes `machine_id` from `machine.user_id` keeps
+    // its loadMachine — the "connection-only" qualifier).
+    if (/\bconst machine\b/.test(text) &&
+        /\bfunction loadMachine\b/.test(text) &&
+        !machineReferencedElsewhere(text)) {
+        text = removeConstDecl(text, 'machine');
+        text = removeFunctionDecl(text, 'loadMachine');
+    }
+    return text;
+}
+/**
+ * Strip the `site:` and `plugins:` properties from an engine config's
+ * `export default { … }` (with their leading comment/whitespace), plus the
+ * now-orphaned connection preamble consts. Returns the rewritten source and the
+ * list of object keys removed (`[]` — source returned unchanged — when there is
+ * nothing connection-related to remove). remote/executor/agent/workspace/hooks/
+ * project/machine_id/loadLocal are left intact.
+ */
+export function stripLegacyConnectionFromConfigSource(source) {
+    const obj = findDefaultExportObject(source);
+    if (!obj)
+        return { text: source, removed: [] };
+    const entries = scanTopLevelProperties(source, obj.bodyStart, obj.bodyEnd);
+    const targets = new Set(['site', 'plugins']);
+    const toRemove = entries.filter((e) => e.key !== undefined && targets.has(e.key));
+    if (toRemove.length === 0)
+        return { text: source, removed: [] };
+    let text = source;
+    for (const e of [...toRemove].sort((a, b) => b.start - a.start)) {
+        text = text.slice(0, e.start) + text.slice(e.end);
+    }
+    text = removeOrphanedPreamble(text);
+    // Report in source order for a stable `site/plugins` message.
+    const removed = ['site', 'plugins'].filter((k) => toRemove.some((e) => e.key === k));
+    return { text, removed };
+}