@gaia-ai/conductor 0.6.0 → 0.6.1

package/README.md

@@ -2,4 +2,4 @@
 
 GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.
 
-Part of the GAIA conductor. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all plugins. Source: https://git.key-tec.de/keytec/gaia (conductor/).
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/cli/config-schema.d.ts

@@ -18,12 +18,36 @@ export interface ConnectionConfigMigration {
     apply(currentText: string): string;
 }
 /**
- * The ordered, contiguous migration chain. Ships EMPTY at v1: nothing below v1
- * is a versioned config (v0 = seed / hand-authored / untouched). The FIRST real
- * shape change adds the first `{ from: 1, to: 2, … }` method here, which bumps
- * the derived CURRENT to 2 automatically. The extension point is real and
- * exercised by tests now, so the first shape change is a one-method addition,
- * never a re-plumb.
+ * GAIA-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadGaiaConfig`'s bases
+ * (config dir / host module / cwd), whereas `@gaia-ai/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@gaia-ai/gaia` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export declare const RENDERER_PLUGIN_PACKAGE = "@gaia-ai/addon-essentials";
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export declare const RENDERER_PLUGIN_ENTRY = "{ plugin: '@gaia-ai/addon-essentials' },";
+/**
+ * GAIA-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `gaia dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export declare function addRendererPluginEntry(text: string): string;
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
+ * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
+ * derives from the chain's last `to` — never hardcode it.
  */
 export declare const CONNECTION_MIGRATIONS: ConnectionConfigMigration[];
 /** The current connection-config schema version — single source of truth. */
@@ -40,6 +64,15 @@ export declare function readConfigSchemaVersion(path: string): number;
 export declare function stripVersionHeader(text: string): string;
 /** Prepend (replacing any existing) a `// @gaia-schema-version <N>` header. */
 export declare function stampVersion(text: string, version: number): string;
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (GAIA-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export declare function stampSchemaVersionField(text: string, version: number): string;
 /**
  * Validate a migration chain is contiguous: each `to === from + 1`, the first
  * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
@@ -49,6 +82,8 @@ export declare function assertContiguous(chain: ConnectionConfigMigration[], cur
 /**
  * Walk the migration chain from `from` up to `to`, applying each method's
  * `apply` in sequence. Input/output text is WITHOUT the version header — the
- * caller stamps CURRENT after. `chain` is injectable for tests.
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
  */
 export declare function applyMigrations(text: string, from: number, to: number, chain?: ConnectionConfigMigration[]): string;

package/dist/src/cli/config-schema.js

@@ -11,15 +11,57 @@ import { readFileSync } from 'node:fs';
 const MARKER_RE = /@gaia-schema-version\s+(\d+)/;
 const HEADER_LINE_RE = /^\/\/ @gaia-schema-version \d+\n/;
 /**
- * The ordered, contiguous migration chain. Ships EMPTY at v1: nothing below v1
- * is a versioned config (v0 = seed / hand-authored / untouched). The FIRST real
- * shape change adds the first `{ from: 1, to: 2, … }` method here, which bumps
- * the derived CURRENT to 2 automatically. The extension point is real and
- * exercised by tests now, so the first shape change is a one-method addition,
- * never a re-plumb.
+ * GAIA-226: the package name whose `plugins[]` entry contributes the `md`
+ * renderer (plus the authoritative JSON:API schema) to a connection config. The
+ * AGGREGATOR is named, not `@dropsh/plugin-markdown` directly: a direct
+ * `@dropsh/*` descriptor is unresolvable from `loadGaiaConfig`'s bases
+ * (config dir / host module / cwd), whereas `@gaia-ai/addon-essentials` is a
+ * real dependency of both the host and the engine and therefore resolves in the
+ * monorepo AND from a global `@gaia-ai/gaia` install. No `export:` is needed —
+ * the package default-exports its factory.
+ */
+export const RENDERER_PLUGIN_PACKAGE = '@gaia-ai/addon-essentials';
+/** The exact `plugins[]` element text the v1→v2 migration and the scaffold emit. */
+export const RENDERER_PLUGIN_ENTRY = `{ plugin: '${RENDERER_PLUGIN_PACKAGE}' },`;
+/** `plugins: [` — captures its own indentation so the inserted element aligns. */
+const PLUGINS_ARRAY_OPEN_RE = /^([ \t]*)plugins:\s*\[[ \t]*$/m;
+/** Whole-line `//` comments — stripped before the presence probe (see below). */
+const LINE_COMMENT_RE = /^[ \t]*\/\/.*$/gm;
+/**
+ * GAIA-226 (v1 → v2): insert the renderer aggregator as the FIRST `plugins[]`
+ * element, so `gaia dropsh --format md` works instead of failing with
+ * `E_CONFIG: Unknown format 'md'. Available: json`.
+ *
+ * A pure TEXT transform — the upgrade runner must never execute a possibly
+ * side-effecting config module. Idempotent: text that already names the package
+ * in CODE is returned unchanged (whole-line `//` comments are stripped for that
+ * probe, so the template's own explanatory header does not read as a hit), and a
+ * config with no `plugins: [` array literal (an `addons: []`-shaped or
+ * hand-reshaped file) is left alone rather than guessed at.
+ */
+export function addRendererPluginEntry(text) {
+    if (text.replace(LINE_COMMENT_RE, '').includes(RENDERER_PLUGIN_PACKAGE)) {
+        return text;
+    }
+    const m = PLUGINS_ARRAY_OPEN_RE.exec(text);
+    if (m === null)
+        return text;
+    const indent = `${m[1]}  `;
+    return text.replace(PLUGINS_ARRAY_OPEN_RE, (line) => `${line}\n${indent}${RENDERER_PLUGIN_ENTRY}`);
+}
+/**
+ * The ordered, contiguous migration chain. v1 was the pre-GAIA-226 shape (auth
+ * plugins only); v2 adds the markdown renderer entry. Nothing below v1 is a
+ * versioned config (v0 = seed / hand-authored / untouched). `GAIA_CONFIG_SCHEMA_VERSION`
+ * derives from the chain's last `to` — never hardcode it.
  */
 export const CONNECTION_MIGRATIONS = [
-// { from: 1, to: 2, description: 'add site.jsonapi_prefix default', apply: (t) => … },
+    {
+        from: 1,
+        to: 2,
+        description: `add the ${RENDERER_PLUGIN_PACKAGE} renderer entry to plugins[]`,
+        apply: addRendererPluginEntry,
+    },
 ];
 /** The current connection-config schema version — single source of truth. */
 export const GAIA_CONFIG_SCHEMA_VERSION = CONNECTION_MIGRATIONS.at(-1)?.to ?? 1;
@@ -49,6 +91,17 @@ export function stripVersionHeader(text) {
 export function stampVersion(text, version) {
     return `// @gaia-schema-version ${version}\n${stripVersionHeader(text)}`;
 }
+/**
+ * Re-stamp the in-body `schema_version: <N>` field, which the generated config
+ * carries alongside the header marker for programmatic reads. The header is the
+ * upgrade decision's source of truth and is stamped by the runner; this keeps the
+ * FIELD from going stale when a migration bumps the version (GAIA-226 — the first
+ * migration is where the two could first disagree). No-op when the field is
+ * absent (a hand-authored config need not carry it).
+ */
+export function stampSchemaVersionField(text, version) {
+    return text.replace(/^([ \t]*)schema_version:\s*\d+\s*,/m, `$1schema_version: ${version},`);
+}
 /**
  * Validate a migration chain is contiguous: each `to === from + 1`, the first
  * migrates from v1, no gaps, and the chain ends at `current` (default CURRENT).
@@ -74,7 +127,9 @@ export function assertContiguous(chain, current = GAIA_CONFIG_SCHEMA_VERSION) {
 /**
  * Walk the migration chain from `from` up to `to`, applying each method's
  * `apply` in sequence. Input/output text is WITHOUT the version header — the
- * caller stamps CURRENT after. `chain` is injectable for tests.
+ * caller stamps CURRENT after. After each step the in-body `schema_version:`
+ * field is re-stamped to that step's `to`, so no individual method has to know
+ * (or hardcode) its own number twice. `chain` is injectable for tests.
  */
 export function applyMigrations(text, from, to, chain = CONNECTION_MIGRATIONS) {
     let cur = from;
@@ -84,7 +139,7 @@ export function applyMigrations(text, from, to, chain = CONNECTION_MIGRATIONS) {
         if (step === undefined) {
             throw new Error(`no migration from v${cur} (chain incomplete)`);
         }
-        out = step.apply(out);
+        out = stampSchemaVersionField(step.apply(out), step.to);
         cur = step.to;
     }
     return out;

package/dist/src/cli/init.js

@@ -2,7 +2,7 @@ import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
 import { machineContextPath, readMachineContext, } from '@gaia-ai/core';
-import { GAIA_CONFIG_SCHEMA_VERSION } from './config-schema.js';
+import { GAIA_CONFIG_SCHEMA_VERSION, RENDERER_PLUGIN_ENTRY, } from './config-schema.js';
 export { machineContextPath, readMachineContext };
 /** JS single-quoted string literal for a trusted, simple value. */
 function q(value) {
@@ -29,10 +29,12 @@ export function renderCommittedConfig(inputs) {
 // IMPORT-FREE (GAIA-78): the plugin slots are \`{ plugin, with }\` descriptors
 // naming the REAL published package, not \`import\`ed constructors.
 // loadConductorConfig resolves each name ESLint-style (config dir → cwd →
-// conductor install). Each plugin package default-exports its factory (no
-// \`export:\`) EXCEPT the multi-export host barrel and the merged herdr workspace
-// (\`@gaia-ai/plugin-herdr\` default-exports the executor, so the workspace names
-// \`export: 'herdrWorkspace'\` — GAIA-139).
+// conductor install). Every addon package default-exports its single factory, so
+// no slot needs an \`export:\` — EXCEPT the merged herdr workspace
+// (\`@gaia-ai/addon-herdr\` default-exports the executor, so the workspace names
+// \`export: 'herdrWorkspace'\` — GAIA-139). GAIA-224 replaced the old
+// \`{ plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' }\` host-barrel
+// descriptor with the real addon package \`@gaia-ai/addon-remote-drupal\`.
 
 // The user-global machine context: identity + connection (incl. secret), shared
 // by every project on this machine. Never committed.
@@ -67,16 +69,16 @@ export default {
   // Lifecycle hooks are executor-owned (GAIA-84): they live at the config top
   // level — NOT on a plugin descriptor's \`with.hooks\`.
   hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' },
-  remote: { plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' },
-  executor: { plugin: '@gaia-ai/plugin-herdr' },
+  remote: { plugin: '@gaia-ai/addon-remote-drupal' },
+  executor: { plugin: '@gaia-ai/addon-herdr' },
   agent: {
-    plugin: '@gaia-ai/plugin-claude',
+    plugin: '@gaia-ai/addon-claude',
     with: { model: local.model ?? 'claude-opus-4-8' },
   },
-  // GAIA-139: the herdr workspace ships in @gaia-ai/plugin-herdr, which
+  // GAIA-139: the herdr workspace ships in @gaia-ai/addon-herdr, which
   // default-exports the EXECUTOR — so the workspace slot names export: 'herdrWorkspace'.
   workspace: {
-    plugin: '@gaia-ai/plugin-herdr',
+    plugin: '@gaia-ai/addon-herdr',
     export: 'herdrWorkspace',
   },
 };
@@ -99,6 +101,9 @@ export function renderGaiaConfig() {
 //
 // plugins[] is consumed by DROPSH, whose resolver has no sole-function
 // auto-pick, so @dropsh/plugin-oauth2 entries MUST name export: 'oauth2Plugin'.
+// The '@gaia-ai/addon-essentials' entry (GAIA-226) needs NO export: — that
+// package default-exports its factory. It contributes the markdown renderer
+// ('gaia dropsh --format md') plus the authoritative JSON:API schema.
 async function loadMachine() {
   try {
     return (await import(\`\${process.env.HOME}/.gaia/machine.config.js\`)).default ?? {};
@@ -123,6 +128,7 @@ export default {
   schema_version: ${GAIA_CONFIG_SCHEMA_VERSION},
   site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
   plugins: [
+    ${RENDERER_PLUGIN_ENTRY}
     {
       plugin: '@dropsh/plugin-oauth2',
       export: 'oauth2Plugin',

package/dist/src/cli/migrate-addon-names.d.ts

@@ -0,0 +1,72 @@
+/** Suffix of the pre-rewrite backup a real (non-dry) rewrite leaves behind. */
+export declare const ADDON_RENAME_BAK_SUFFIX = ".pre-addon-rename.bak";
+/**
+ * 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 declare const RENAMED_ADDONS: readonly ["auth-basic", "claude", "codex", "deployment", "dropsh", "essentials", "fake", "gaia-ui", "herdr", "kimi", "opencode", "pi", "remote-drupal", "workspace-git"];
+/**
+ * Where each export of the DELETED `@gaia-ai/core/plugins` host barrel lives now.
+ *
+ * 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 declare const CORE_PLUGINS_BARREL_EXPORTS: Readonly<Record<string, {
+    target: string;
+    defaultExport: boolean;
+}>>;
+/** Which surface a config file speaks — decides the ambiguous builtins mapping. */
+export type ConfigSurface = 'connection' | 'engine';
+/**
+ * Rewrite the legacy specifiers in one config's SOURCE TEXT — all three: the
+ * renamed `@gaia-ai/plugin-*` packages, the deleted `@gaia-ai/core/builtins`
+ * preset, and the deleted `@gaia-ai/core/plugins` barrel descriptors. 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 declare function migrateAddonNames(text: string, surface: ConfigSurface): {
+    text: string;
+    count: number;
+};
+/** The outcome of the rename pass over a single config file. */
+export interface AddonRenameResult {
+    /** Report line, in the shape of the other upgrade steps. */
+    action: string;
+    /** `- old` / `+ new` lines for the rewritten specifiers. */
+    diff: string[];
+    /** Number of rewritten specifiers. */
+    count: number;
+}
+/**
+ * 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 declare function migrateAddonNamesInFile(path: string, surface: ConfigSurface, opts?: {
+    dryRun?: boolean;
+}): AddonRenameResult | undefined;
+/**
+ * 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 declare function runAddonRenameMigration(opts?: {
+    gaiaDirs: string[];
+    dryRun?: boolean;
+}): {
+    actions: string[];
+    changed: boolean;
+};

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

@@ -0,0 +1,318 @@
+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. The `@gaia-ai/gaia/plugins`
+// barrel is deliberately NOT covered: it still exists as a back-compat
+// aggregator. `@gaia-ai/core/plugins` has no such reprieve — it is gone, and the
+// pre-GAIA-224 project docs explicitly told configs to name `@gaia-ai/core/plugins`
+// and NOT `@gaia-ai/gaia/plugins` (core resolved from both the dev monorepo and a
+// global install; the meta package did not), so real installs DO name the deleted
+// one. See `CORE_PLUGINS_BARREL_EXPORTS`.
+//
+// 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`, …),
+//     the `plugins:`/`addons:` config KEYS and the `@gaia-ai/gaia/plugins`
+//     subpath barrel are excluded BY CONSTRUCTION: they carry neither the
+//     `@gaia-ai/plugin-` scope prefix nor the `@gaia-ai/core/` path.
+//   - 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 DELETED `@gaia-ai/core/plugins` host barrel lives now.
+ *
+ * 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 },
+};
+const BARREL_PATH = '@gaia-ai/core/plugins';
+/** `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: '@gaia-ai/core/plugins', 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 `@gaia-ai/core/plugins` descriptors 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 three: the
+ * renamed `@gaia-ai/plugin-*` packages, the deleted `@gaia-ai/core/builtins`
+ * preset, and the deleted `@gaia-ai/core/plugins` barrel descriptors. 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 };
+}