@gaia-ai/conductor 0.6.0 → 0.6.2

package/dist/src/cli/migrate-addon-names.js

@@ -0,0 +1,351 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { listConductorConfigFiles } from '../config.js';
+// GAIA-224 (Finding 8b, spec v3 decision 17): the `gaia upgrade` RENAME pass.
+//
+// The addon packages were renamed `@gaia-ai/plugin-<name>` → `@gaia-ai/addon-<name>`
+// (decision 14) and the core barrels `@gaia-ai/core/{builtins,plugins}` were
+// deleted (Finding 6). Both are npm-breaking for an existing install, whose
+// `.gaia/` configs still name the old packages — so `gaia upgrade` rewrites them
+// in the user's PROJECT `./.gaia/` and HOME `~/.gaia/` configs.
+//
+// All THREE deleted/renamed specifiers are covered, and — GAIA-230 — so is the
+// FOURTH: the `@gaia-ai/gaia/plugins` host barrel.
+//
+// GAIA-224 excluded that barrel on the premise that it "still exists as a
+// back-compat aggregator", so a config naming it keeps resolving. That premise is
+// INSTALL-DEPENDENT and false for a dev-clone install: `@gaia-ai/gaia` is the
+// workspace's leaf SINK, so nothing depends on it and it is absent from
+// `gaia-cli/node_modules/@gaia-ai/`; it is also the only package exporting
+// `./plugins` (`@gaia-ai/core`'s export map has no such subpath). The `gaia` shim
+// prefers a checkout's own build over the global install by design, so exactly
+// there the barrel is unresolvable and that one config line dies while its
+// sibling `addon-*` slots resolve fine.
+//
+// The barrel itself keeps existing — this is not repairing a dead reference, it is
+// making configs stop NAMING a barrel the project docs already tell them not to
+// name. Both barrels are therefore migrated the same closed-set way, over the same
+// `CORE_PLUGINS_BARREL_EXPORTS` table. Two deliberate consequences:
+//   - the table is a SUPERSET of what `@gaia-ai/gaia/plugins` actually re-exports
+//     (`host/src/plugins-barrel.ts` omits the fakes on purpose — they are
+//     workspace-only and must not be a published package's dependency). Mapping
+//     them anyway is right: such a descriptor is broken today, and retargeting it
+//     at `@gaia-ai/addon-fake` fixes it.
+//   - `loadInstructions` IS a barrel export but is not a plugin factory and is
+//     absent from the table, so it stays untouched — as does any other unmapped
+//     `export:`.
+//
+// Covered per config dir:
+//   - the connection config `gaia.config.js` (its `plugins[]` / `addons[]`);
+//   - EVERY engine config the loader itself recognises — the default
+//     `conductor.config.js` AND each `<variant>.conductor.config.js`
+//     (GAIA-137 naming convention, enumerated via `listConductorConfigFiles` so
+//     the pass and the loader can never disagree). A legacy `conductor.config.js`
+//     still carrying `site`/`plugins` (the back-compat connection source) is
+//     therefore covered too, and its `plugins[]` entries are mapped on the
+//     CONNECTION surface — see `builtinsTargetFor`.
+//
+// Safety (decision 18 + the v3 risk register):
+//   - Replacement is anchored on a CLOSED set of 14 known package names inside
+//     a matched quote pair — never a broad `@gaia-ai/plugin-.*` sweep. A
+//     hand-written config's comments, formatting and unrelated code survive.
+//     The `@gaia-ai/core/plugins` rewrite is likewise closed-set: it is driven by
+//     the barrel's OWN export list, and an export name outside that list is left
+//     untouched rather than retargeted at a guess.
+//   - `*Plugin` interface identifiers (`RemotePlugin`, `herdrExecutorPlugin`, …)
+//     and the `plugins:`/`addons:` config KEYS are excluded BY CONSTRUCTION: a
+//     replacement only ever fires on a full quoted specifier, and none of those
+//     is one.
+//   - Idempotent: a config already on `addon-*` produces zero matches and is
+//     left BYTE-unchanged (no rewrite, no backup, no report line).
+//   - `--dry-run` prints the line diff and writes nothing.
+//   - A real rewrite backs the original up next to the file, like the
+//     schema-migration path does.
+/** Suffix of the pre-rewrite backup a real (non-dry) rewrite leaves behind. */
+export const ADDON_RENAME_BAK_SUFFIX = '.pre-addon-rename.bak';
+const AUTH_BASIC = '@gaia-ai/addon-auth-basic';
+const REMOTE_DRUPAL = '@gaia-ai/addon-remote-drupal';
+const WORKSPACE_GIT = '@gaia-ai/addon-workspace-git';
+const FAKE = '@gaia-ai/addon-fake';
+/**
+ * The 14 addon packages renamed by GAIA-224 (spec v3 decision 14), including
+ * the GAIA-220 `pi` agent addon merged in from develop. A CLOSED
+ * set — the pass rewrites only these exact specifiers, so an unknown
+ * `@gaia-ai/plugin-something` is left alone rather than silently retargeted at a
+ * package that does not exist.
+ */
+export const RENAMED_ADDONS = [
+    'auth-basic',
+    'claude',
+    'codex',
+    'deployment',
+    'dropsh',
+    'essentials',
+    'fake',
+    'gaia-ui',
+    'herdr',
+    'kimi',
+    'opencode',
+    'pi',
+    'remote-drupal',
+    'workspace-git',
+];
+/**
+ * `'@gaia-ai/plugin-<known>'` (or `"…"` / `` `…` ``), with an optional subpath
+ * (`/preset`), inside a MATCHED quote pair. The quote pair + the closing anchor
+ * are what make this an exact-specifier match: `@gaia-ai/plugin-herdr-x` cannot
+ * match `herdr`, and a bare `RemotePlugin` identifier cannot match at all.
+ * Longest name first so a longer name always wins the alternation.
+ */
+const QUOTED_LEGACY_ADDON = new RegExp(`(['"\`])@gaia-ai/plugin-(${[...RENAMED_ADDONS]
+    .sort((a, b) => b.length - a.length)
+    .join('|')})((?:/[^'"\`]*)?)\\1`, 'g');
+/** `'@gaia-ai/core/builtins'` inside a matched quote pair (the deleted preset). */
+const QUOTED_LEGACY_BUILTINS = /(['"`])@gaia-ai\/core\/builtins\1/g;
+/**
+ * Where each export of the host barrels lives now — the DELETED
+ * `@gaia-ai/core/plugins` and (GAIA-230) the meta package's
+ * `@gaia-ai/gaia/plugins`, which is unresolvable from a dev-clone install.
+ *
+ * The key set is the barrel's own export list — `core/src/plugins/registry-exports.ts`
+ * as of the commit that deleted it — re-pointed at the addon that owns each
+ * factory today. `defaultExport` records whether the target package
+ * DEFAULT-exports exactly that factory; when it does, the descriptor's `export:`
+ * becomes redundant and is dropped.
+ *
+ * Deliberately absent, so they are left untouched:
+ *   - `selectRemote`/`selectWorkspace`/`selectExecutor`/`selectAgent(s)` — moved
+ *     to `@gaia-ai/conductor/contract`, but they are config-shape SELECTORS, not
+ *     plugin factories, so no descriptor can legitimately name them;
+ *   - any other/unknown export name — a config naming one is reported by the
+ *     loader rather than silently retargeted at a package that may not have it.
+ */
+export const CORE_PLUGINS_BARREL_EXPORTS = {
+    DrupalGaiaRemote: { target: REMOTE_DRUPAL, defaultExport: false },
+    FakeGaiaRemote: { target: FAKE, defaultExport: false },
+    FakeWorkspace: { target: FAKE, defaultExport: false },
+    GitWorkspace: { target: WORKSPACE_GIT, defaultExport: false },
+    basicAuthProvider: { target: AUTH_BASIC, defaultExport: true },
+    drupalRemote: { target: REMOTE_DRUPAL, defaultExport: true },
+    // @gaia-ai/addon-fake ships the whole deterministic triple as NAMED exports
+    // (no default), so these keep their `export:`.
+    fakeRemote: { target: FAKE, defaultExport: false },
+    fakeWorkspace: { target: FAKE, defaultExport: false },
+    gitWorkspace: { target: WORKSPACE_GIT, defaultExport: true },
+};
+/**
+ * The host-barrel specifiers a descriptor may name. Both map through
+ * `CORE_PLUGINS_BARREL_EXPORTS`: `@gaia-ai/core/plugins` is DELETED, and
+ * `@gaia-ai/gaia/plugins` (GAIA-230) is unresolvable from a dev-clone install
+ * because the meta package that exports it is the workspace's leaf sink.
+ */
+export const HOST_BARREL_PATHS = [
+    '@gaia-ai/core/plugins',
+    '@gaia-ai/gaia/plugins',
+];
+/** The two barrel specifiers as one non-capturing regex alternation, so the
+ *  backreference numbers in the descriptor patterns below are unaffected. */
+const BARREL_PATH = `(?:${HOST_BARREL_PATHS.join('|')})`;
+/** `plugin:` / `use:` — the two descriptor keys that name a package. */
+const PKG_KEY = '(?:plugin|use)';
+/** A JS identifier, i.e. an `export:` value the barrel could have carried. */
+const IDENT = String.raw `[A-Za-z_$][\w$]*`;
+/**
+ * `plugin: '<barrel>', export: 'drupalRemote'` — the barrel
+ * descriptor in its written order, single/double/back quoted, one line or many
+ * (`\s` spans newlines). Requiring the `export:` to be ADJACENT is what keeps
+ * this from ever pairing a barrel mention with an unrelated slot's `export:`.
+ */
+const BARREL_THEN_EXPORT = new RegExp(`(${PKG_KEY}\\s*:\\s*)(['"\`])${BARREL_PATH}\\2(\\s*,\\s*export\\s*:\\s*)(['"\`])(${IDENT})\\4`, 'g');
+/** The same descriptor with the keys written the other way round. */
+const EXPORT_THEN_BARREL = new RegExp(`export\\s*:\\s*(['"\`])(${IDENT})\\1(\\s*,\\s*)(${PKG_KEY}\\s*:\\s*)(['"\`])${BARREL_PATH}\\5`, 'g');
+/**
+ * Rewrite the host-barrel descriptors (both specifiers) in one config's source text.
+ *
+ * A mapped descriptor becomes `<key>: '<addon>'` — with the `export:` DROPPED
+ * when the addon default-exports that factory *and* the whole descriptor sits on
+ * one line, so the rewrite stays line-local (the index-aligned report diff and
+ * `migrateAddonNames`' line-count invariant depend on that). A multi-line
+ * descriptor keeps its `export:`: every mapped name is also a NAMED export of its
+ * target addon, so the result resolves either way — only the redundancy survives.
+ *
+ * Left byte-untouched: an unmapped/unknown `export:` name, and a barrel
+ * occurrence with no adjacent `export:` at all (a bare `addons: ['…/plugins']` or
+ * a prose mention) — neither carries enough information to pick a target.
+ */
+function migrateBarrelDescriptors(text) {
+    let count = 0;
+    const rewrite = (whole, name, keyPrefix, quote, keepExport) => {
+        const hit = CORE_PLUGINS_BARREL_EXPORTS[name];
+        if (hit === undefined)
+            return whole;
+        count++;
+        const spec = `${keyPrefix}${quote}${hit.target}${quote}`;
+        if (hit.defaultExport && !whole.includes('\n'))
+            return spec;
+        return `${spec}${keepExport()}`;
+    };
+    const out = text
+        .replace(BARREL_THEN_EXPORT, (whole, keyPrefix, pkgQuote, exportSep, nameQuote, name) => rewrite(whole, name, keyPrefix, pkgQuote, () => `${exportSep}${nameQuote}${name}${nameQuote}`))
+        .replace(EXPORT_THEN_BARREL, (whole, nameQuote, name, sep, keyPrefix, pkgQuote) => rewrite(whole, name, keyPrefix, pkgQuote, () => `${sep}export: ${nameQuote}${name}${nameQuote}`));
+    return { text: out, count };
+}
+/**
+ * The object-literal entry that encloses `at`, e.g.
+ * `{ use: '@gaia-ai/core/builtins', with: { basic: token } }`. Empty string when
+ * the occurrence is a BARE string entry (`addons: ['@gaia-ai/core/builtins']`) —
+ * the backward scan then hits the array/argument boundary first.
+ */
+function enclosingEntry(text, at) {
+    let depth = 0;
+    let start = -1;
+    for (let i = at; i >= 0; i--) {
+        const c = text[i];
+        if (c === '}')
+            depth++;
+        else if (c === '{') {
+            if (depth === 0) {
+                start = i;
+                break;
+            }
+            depth--;
+        }
+        else if (depth === 0 && (c === '[' || c === '(' || c === ';')) {
+            break;
+        }
+    }
+    if (start < 0)
+        return '';
+    let d = 0;
+    for (let i = start; i < text.length; i++) {
+        const c = text[i];
+        if (c === '{')
+            d++;
+        else if (c === '}') {
+            d--;
+            if (d === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return text.slice(start);
+}
+/** The nearest `plugins:` / `addons:` array key BEFORE `at`, if any. */
+function nearestArrayKey(text, at) {
+    const re = /\b(plugins|addons)\s*:/g;
+    let last;
+    for (let m = re.exec(text); m !== null && m.index < at; m = re.exec(text)) {
+        last = m[1];
+    }
+    return last;
+}
+/**
+ * `@gaia-ai/core/builtins` was ONE preset contributing to BOTH surfaces, so its
+ * replacement is per-occurrence (spec v3 decision 17, the Finding 6/8 interplay):
+ *
+ *   | signal (first that applies)                  | target                      |
+ *   | the entry carries a `basic` token            | `@gaia-ai/addon-auth-basic`  |
+ *   | the nearest array key is `plugins:`          | `@gaia-ai/addon-auth-basic`  |
+ *   | the file is a connection config              | `@gaia-ai/addon-auth-basic`  |
+ *   | otherwise (engine `addons:` / a slot)        | `@gaia-ai/addon-remote-drupal` |
+ *
+ * The `plugins:` rule is what makes a LEGACY `conductor.config.js` (engine file
+ * name, but still carrying a connection `site`/`plugins`) come out right.
+ */
+function builtinsTargetFor(text, at, surface) {
+    if (/basic/i.test(enclosingEntry(text, at)))
+        return AUTH_BASIC;
+    if (nearestArrayKey(text, at) === 'plugins')
+        return AUTH_BASIC;
+    return surface === 'connection' ? AUTH_BASIC : REMOTE_DRUPAL;
+}
+/**
+ * Rewrite the legacy specifiers in one config's SOURCE TEXT — all of them: the
+ * renamed `@gaia-ai/plugin-*` packages, the deleted `@gaia-ai/core/builtins`
+ * preset, and the host-barrel descriptors naming either `@gaia-ai/core/plugins`
+ * (deleted) or `@gaia-ai/gaia/plugins` (GAIA-230). Pure; line
+ * count is preserved (every replacement is line-local), which is what lets the
+ * reported diff be a plain index-aligned line diff.
+ */
+export function migrateAddonNames(text, surface) {
+    let count = 0;
+    let out = text.replace(QUOTED_LEGACY_ADDON, (_m, quote, name, subpath) => {
+        count++;
+        return `${quote}@gaia-ai/addon-${name}${subpath}${quote}`;
+    });
+    out = out.replace(QUOTED_LEGACY_BUILTINS, (_m, quote, offset, whole) => {
+        count++;
+        return `${quote}${builtinsTargetFor(whole, offset, surface)}${quote}`;
+    });
+    const barrel = migrateBarrelDescriptors(out);
+    return { text: barrel.text, count: count + barrel.count };
+}
+/** An index-aligned `- old` / `+ new` line diff (line count is preserved). */
+function lineDiff(before, after) {
+    const a = before.split('\n');
+    const b = after.split('\n');
+    const out = [];
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        if (a[i] === b[i])
+            continue;
+        if (a[i] !== undefined)
+            out.push(`  - ${a[i]}`);
+        if (b[i] !== undefined)
+            out.push(`  + ${b[i]}`);
+    }
+    return out;
+}
+/**
+ * Rename pass over ONE config file. Returns `undefined` when the file is absent
+ * or already on the new names (idempotency: no write, no backup, no report
+ * line — the file stays byte-identical).
+ */
+export function migrateAddonNamesInFile(path, surface, opts = {}) {
+    if (!existsSync(path))
+        return undefined;
+    const before = readFileSync(path, 'utf8');
+    const { text: after, count } = migrateAddonNames(before, surface);
+    if (count === 0 || after === before)
+        return undefined;
+    const diff = lineDiff(before, after);
+    const what = `${count} legacy addon reference(s) → @gaia-ai/addon-*`;
+    if (opts.dryRun ?? false) {
+        return { action: `would rewrite ${path} (${what})`, diff, count };
+    }
+    const bak = `${path}${ADDON_RENAME_BAK_SUFFIX}`;
+    writeFileSync(bak, before, 'utf8');
+    writeFileSync(path, after, 'utf8');
+    return {
+        action: `rewrote ${path} (${what}; backup ${bak})`,
+        diff,
+        count,
+    };
+}
+/**
+ * Rename pass over every recognised config in the given `.gaia/` dirs (project
+ * + home). Emits report lines ONLY for files it actually rewrites, so an install
+ * already on `addon-*` adds no noise to the upgrade report.
+ */
+export function runAddonRenameMigration(opts = { gaiaDirs: [] }) {
+    const actions = [];
+    let changed = false;
+    const seen = new Set();
+    for (const dir of opts.gaiaDirs) {
+        if (seen.has(dir) || !existsSync(dir))
+            continue;
+        seen.add(dir);
+        const files = [
+            [join(dir, 'gaia.config.js'), 'connection'],
+            ...listConductorConfigFiles(dir).map((f) => [join(dir, f), 'engine']),
+        ];
+        for (const [path, surface] of files) {
+            const res = migrateAddonNamesInFile(path, surface, {
+                dryRun: opts.dryRun ?? false,
+            });
+            if (res === undefined)
+                continue;
+            actions.push(res.action, ...res.diff);
+            changed = true;
+        }
+    }
+    return { actions, changed };
+}

package/dist/src/cli/upgrade.d.ts

@@ -5,6 +5,13 @@ export interface UpgradeReport {
     /** true when nothing needed doing. */
     alreadyCurrent: boolean;
 }
+/**
+ * GAIA-218: what `gaia upgrade` does to the PROJECT connection override. The
+ * pure routine defaults to `'skip'` (non-interactive / `conductor init`): never
+ * create, never migrate, never delete. The host CLI resolves `'create'` /
+ * `'remove'` from an opt-in TTY prompt.
+ */
+export type ProjectConnectionChoice = 'skip' | 'create' | 'remove';
 /** The outcome of routing a single connection-config file. */
 interface ConnectionUpgradeResult {
     action: string;
@@ -29,10 +36,18 @@ export declare function runConnectionUpgrade(path: string, opts?: {
     current?: number;
     chain?: ConnectionConfigMigration[];
 }): ConnectionUpgradeResult;
+/**
+ * The absolute path of the PROJECT connection override (`./.gaia/gaia.config.js`)
+ * when one exists for `cwd`, else `undefined`. Used by the host CLI to decide
+ * whether to ask "remove this override?" vs "create an override?" (GAIA-218).
+ */
+export declare function hasProjectConnection(cwd: string): string | undefined;
 /** Run the migration. Pure w.r.t. injected `cwd`/`home`; `dryRun` suppresses writes. */
 export declare function runUpgrade(opts?: {
     cwd?: string;
     home?: string;
     dryRun?: boolean;
+    /** GAIA-218: what to do with the PROJECT connection override (default skip). */
+    projectConnection?: ProjectConnectionChoice;
 }): UpgradeReport;
 export {};

package/dist/src/cli/upgrade.js

@@ -1,9 +1,11 @@
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync, } from 'node:fs';
+import { chmodSync, copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
+import { listConductorConfigFiles, stripLegacyConnectionFromConfigSource, } from '../config.js';
 import { applyMigrations, CONNECTION_MIGRATIONS, GAIA_CONFIG_SCHEMA_VERSION, readConfigSchemaVersion, stampVersion, stripVersionHeader, } from './config-schema.js';
 import { renderGaiaConfig } from './init.js';
+import { runAddonRenameMigration } from './migrate-addon-names.js';
 const GAIA_DIR = '.gaia';
 const DEFAULT_ENGINE = 'conductor.config.js';
 const VARIANT_SUFFIX = '.conductor.config.js';
@@ -98,22 +100,86 @@ export function runConnectionUpgrade(path, opts = {}) {
         changed: true,
     };
 }
+/**
+ * The absolute path of the PROJECT connection override (`./.gaia/gaia.config.js`)
+ * when one exists for `cwd`, else `undefined`. Used by the host CLI to decide
+ * whether to ask "remove this override?" vs "create an override?" (GAIA-218).
+ */
+export function hasProjectConnection(cwd) {
+    const gaiaDir = findGaiaDir(cwd);
+    if (gaiaDir === undefined)
+        return undefined;
+    const p = join(gaiaDir, CONNECTION);
+    return existsSync(p) ? p : undefined;
+}
 /** Run the migration. Pure w.r.t. injected `cwd`/`home`; `dryRun` suppresses writes. */
 export function runUpgrade(opts = {}) {
     const cwd = opts.cwd ?? process.cwd();
     const home = opts.home ?? homedir();
     const dry = opts.dryRun ?? false;
+    const choice = opts.projectConnection ?? 'skip';
     const actions = [];
     let changed = false;
-    // 1. Project connection config (schema-versioned seed/migrate).
     const gaiaDir = findGaiaDir(cwd);
+    // 0. GAIA-218 (AC-7): strip legacy connection/auth (`site`/`plugins` + the
+    //    orphaned connection preamble) from EVERY engine config in the `.gaia/`
+    //    dir — the supported enumeration only, never an unrelated `*.config.js`.
+    if (gaiaDir !== undefined) {
+        for (const file of listConductorConfigFiles(gaiaDir)) {
+            const path = join(gaiaDir, file);
+            if (!existsSync(path))
+                continue;
+            const original = readFileSync(path, 'utf8');
+            const { text, removed } = stripLegacyConnectionFromConfigSource(original);
+            if (removed.length === 0)
+                continue;
+            if (dry) {
+                actions.push(`would strip ${removed.join('/')} from ${path}`);
+            }
+            else {
+                writeFileSync(`${path}.legacy.bak`, original, 'utf8');
+                writeFileSync(path, text, 'utf8');
+                actions.push(`stripped ${removed.join('/')} from ${path} (backup ${path}.legacy.bak)`);
+            }
+            changed = true;
+        }
+    }
+    // 1. Project connection config — decision-driven (GAIA-218, default skip).
     if (gaiaDir !== undefined && hasEngineConfig(gaiaDir)) {
-        const res = runConnectionUpgrade(join(gaiaDir, CONNECTION), {
-            dryRun: dry,
-            label: 'project connection config',
-        });
-        actions.push(res.action);
-        changed = changed || res.changed;
+        const projectConn = join(gaiaDir, CONNECTION);
+        if (choice === 'create') {
+            if (existsSync(projectConn)) {
+                actions.push(`project connection: unchanged (${projectConn} exists — kept, not migrated)`);
+            }
+            else {
+                const res = runConnectionUpgrade(projectConn, {
+                    dryRun: dry,
+                    label: 'project connection config',
+                });
+                actions.push(res.action);
+                changed = changed || res.changed;
+            }
+        }
+        else if (choice === 'remove') {
+            if (existsSync(projectConn)) {
+                const bak = `${projectConn}.removed.bak`;
+                if (dry) {
+                    actions.push(`would remove ${projectConn} (project connection override)`);
+                }
+                else {
+                    copyFileSync(projectConn, bak);
+                    rmSync(projectConn);
+                    actions.push(`removed ${projectConn} (project connection override; backup ${bak})`);
+                }
+                changed = true;
+            }
+            else {
+                actions.push('project connection: unchanged (no project override to remove)');
+            }
+        }
+        else {
+            actions.push('project connection: unchanged');
+        }
     }
     // 2. Machine context move (secret-bearing — never schema-migrated).
     const legacy = legacyMachinePath(home);
@@ -139,5 +205,18 @@ export function runUpgrade(opts = {}) {
     });
     actions.push(homeRes.action);
     changed = changed || homeRes.changed;
+    // 4. GAIA-224 addon rename pass over the project + home `.gaia/` configs
+    //    (connection `gaia.config.js` + every recognised engine config). Runs LAST
+    //    so a config seeded/migrated above — already on the current names — is a
+    //    zero-match no-op. Reports only the files it actually rewrites.
+    const rename = runAddonRenameMigration({
+        gaiaDirs: [
+            ...(gaiaDir === undefined ? [] : [gaiaDir]),
+            join(home, GAIA_DIR),
+        ],
+        dryRun: dry,
+    });
+    actions.push(...rename.actions);
+    changed = changed || rename.changed;
     return { actions, alreadyCurrent: !changed };
 }

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

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