@gaia-ai/conductor 0.5.5 → 0.6.1

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 };
+}

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

@@ -0,0 +1,53 @@
+import { type ConnectionConfigMigration } from './config-schema.js';
+export interface UpgradeReport {
+    /** Human-readable action lines (what changed / was already current). */
+    actions: string[];
+    /** 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;
+    changed: boolean;
+}
+/**
+ * Route a single connection-config `path` against the schema version (GAIA-216).
+ * `label` names the file for the report; `current`/`chain` are injectable for
+ * tests (default to the shipped registry). Never executes the config module —
+ * the decision is a regex read of the header marker.
+ *
+ *   | existing marker        | action                                          |
+ *   | absent (no file)       | seed: render current template, stamp CURRENT    |
+ *   | `== CURRENT`           | kept (byte-identical)                           |
+ *   | `1..CURRENT-1` (stale) | back up `.v<old>.bak`, run chain → stamp CURRENT |
+ *   | `0` (unversioned)      | kept (do not clobber hand edits)                |
+ *   | `> CURRENT` (newer)    | kept (refuse to downgrade)                       |
+ */
+export declare function runConnectionUpgrade(path: string, opts?: {
+    dryRun?: boolean;
+    label?: string;
+    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

@@ -0,0 +1,222 @@
+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';
+const CONNECTION = 'gaia.config.js';
+/** Walk from cwd root-ward to the nearest `.gaia/` dir. */
+function findGaiaDir(cwd) {
+    let dir = resolve(cwd);
+    for (;;) {
+        const g = join(dir, GAIA_DIR);
+        if (existsSync(g))
+            return g;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+function hasEngineConfig(gaiaDir) {
+    return readdirSync(gaiaDir).some((f) => f === DEFAULT_ENGINE || f.endsWith(VARIANT_SUFFIX));
+}
+function legacyMachinePath(home) {
+    return join(home, '.config', 'conductor', 'conductor.config.machine.js');
+}
+function canonicalMachinePath(home) {
+    return join(home, GAIA_DIR, 'machine.config.js');
+}
+/**
+ * Route a single connection-config `path` against the schema version (GAIA-216).
+ * `label` names the file for the report; `current`/`chain` are injectable for
+ * tests (default to the shipped registry). Never executes the config module —
+ * the decision is a regex read of the header marker.
+ *
+ *   | existing marker        | action                                          |
+ *   | absent (no file)       | seed: render current template, stamp CURRENT    |
+ *   | `== CURRENT`           | kept (byte-identical)                           |
+ *   | `1..CURRENT-1` (stale) | back up `.v<old>.bak`, run chain → stamp CURRENT |
+ *   | `0` (unversioned)      | kept (do not clobber hand edits)                |
+ *   | `> CURRENT` (newer)    | kept (refuse to downgrade)                       |
+ */
+export function runConnectionUpgrade(path, opts = {}) {
+    const dry = opts.dryRun ?? false;
+    const label = opts.label ?? 'connection config';
+    const current = opts.current ?? GAIA_CONFIG_SCHEMA_VERSION;
+    const chain = opts.chain ?? CONNECTION_MIGRATIONS;
+    if (!existsSync(path)) {
+        if (!dry) {
+            mkdirSync(dirname(path), { recursive: true });
+            writeFileSync(path, renderGaiaConfig(), 'utf8');
+        }
+        return {
+            action: `${dry ? 'would write' : 'wrote'} ${path} (${label}, schema v${current})`,
+            changed: true,
+        };
+    }
+    const version = readConfigSchemaVersion(path);
+    if (version === current) {
+        return {
+            action: `kept ${path} (${label}, schema v${current} — up to date)`,
+            changed: false,
+        };
+    }
+    if (version === 0) {
+        return {
+            action: `kept ${path} (${label}, unversioned — pass --force to regenerate)`,
+            changed: false,
+        };
+    }
+    if (version > current) {
+        return {
+            action: `kept ${path} (${label}, schema v${version} newer than gaia's v${current} — not downgrading)`,
+            changed: false,
+        };
+    }
+    // 1..current-1: migrate via the per-version chain.
+    const steps = chain
+        .filter((m) => m.from >= version && m.to <= current)
+        .map((m) => m.description)
+        .join('; ') || 'regenerate';
+    if (dry) {
+        return {
+            action: `would migrate ${path} schema v${version}→v${current} (steps: ${steps})`,
+            changed: true,
+        };
+    }
+    const original = readFileSync(path, 'utf8');
+    const bak = `${path}.v${version}.bak`;
+    writeFileSync(bak, original, 'utf8');
+    const migrated = applyMigrations(stripVersionHeader(original), version, current, chain);
+    writeFileSync(path, stampVersion(migrated, current), 'utf8');
+    return {
+        action: `migrated ${path} schema v${version}→v${current} (steps: ${steps}; backup ${bak})`,
+        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;
+    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 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);
+    const canonical = canonicalMachinePath(home);
+    if (existsSync(canonical)) {
+        actions.push(`kept ${canonical} (machine context already migrated)`);
+    }
+    else if (existsSync(legacy)) {
+        if (!dry) {
+            mkdirSync(dirname(canonical), { recursive: true });
+            copyFileSync(legacy, canonical);
+            chmodSync(canonical, 0o600);
+            // Leave a re-export shim at the legacy path so an un-upgraded config still resolves.
+            writeFileSync(legacy, `// Moved to ${canonical} by \`gaia upgrade\` (GAIA-201).\nexport { default } from '${pathToFileURL(canonical).href}';\n`, 'utf8');
+        }
+        actions.push(`${dry ? 'would move' : 'moved'} ${legacy} → ${canonical} (machine context, 0600 + shim)`);
+        changed = true;
+    }
+    // 3. Home connection config (schema-versioned seed/migrate).
+    const homeRes = runConnectionUpgrade(join(home, GAIA_DIR, CONNECTION), {
+        dryRun: dry,
+        label: 'home connection config',
+    });
+    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/cli/version-check.js

@@ -81,8 +81,12 @@ export function updateNotice(current, latest) {
         return null;
     if (!semver.gt(latest, current))
         return null;
+    // Two distinct steps, apt-style: first get the newer CODE, then migrate the
+    // CONFIG. There is no `gaia update` command — the CLI is a global npm package,
+    // so code is updated via npm; `gaia upgrade` then migrates the config shape.
     return (`A new gaia version is available: ${current} → ${latest}\n` +
-        'Run `gaia update` to upgrade.');
+        'Run `npm install -g @gaia-ai/gaia@latest` to update the CLI, ' +
+        'then `gaia upgrade` to migrate your config.');
 }
 const defaultSpawn = (cmd, args) => new Promise((resolve) => {
     const child = spawn(cmd, args, { stdio: 'inherit', shell: false });