@gaia-ai/conductor 0.5.4 → 0.6.0

package/dist/src/cli/conductor-registry.d.ts

@@ -0,0 +1,7 @@
+export type { ConductorRegistryEntry } from '@gaia-ai/core';
+import { conductorRegistryPath, getRegisteredConductor, listRegisteredConductors, registerConductor, removeConductor } from '@gaia-ai/core';
+export { conductorRegistryPath };
+export declare const list: typeof listRegisteredConductors;
+export declare const get: typeof getRegisteredConductor;
+export declare const register: typeof registerConductor;
+export declare const remove: typeof removeConductor;

package/dist/src/cli/conductor-registry.js

@@ -0,0 +1,6 @@
+import { conductorRegistryPath, getRegisteredConductor, listRegisteredConductors, registerConductor, removeConductor, } from '@gaia-ai/core';
+export { conductorRegistryPath };
+export const list = listRegisteredConductors;
+export const get = getRegisteredConductor;
+export const register = registerConductor;
+export const remove = removeConductor;

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

@@ -0,0 +1,54 @@
+/**
+ * A single, discrete, testable upgrade method `vN → vN+1`, registered in order —
+ * exactly like a Drupal `hook_update_N` chain. `gaia upgrade` resolves a config's
+ * current version and applies each method in sequence up to CURRENT (it does not
+ * blindly overwrite), so a method can PRESERVE operator-set fields across a bump.
+ */
+export interface ConnectionConfigMigration {
+    /** The schema version this method upgrades FROM. */
+    from: number;
+    /** The schema version this method upgrades TO (=== from + 1). */
+    to: number;
+    /** What shape change this method performs (human-readable). */
+    description: string;
+    /**
+     * Upgrade the config text from `from` to `to`, returning the new file text
+     * WITHOUT the version header — the runner re-stamps `@gaia-schema-version to`.
+     */
+    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.
+ */
+export declare const CONNECTION_MIGRATIONS: ConnectionConfigMigration[];
+/** The current connection-config schema version — single source of truth. */
+export declare const GAIA_CONFIG_SCHEMA_VERSION: number;
+/** Parse the `@gaia-schema-version` marker from config text; `0` when absent. */
+export declare function schemaVersionOf(text: string): number;
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export declare function readConfigSchemaVersion(path: string): number;
+/** Strip a leading `// @gaia-schema-version <N>` header line, if present. */
+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;
+/**
+ * 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).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export declare function assertContiguous(chain: ConnectionConfigMigration[], current?: number): void;
+/**
+ * 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.
+ */
+export declare function applyMigrations(text: string, from: number, to: number, chain?: ConnectionConfigMigration[]): string;

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

@@ -0,0 +1,91 @@
+import { readFileSync } from 'node:fs';
+// GAIA-216: schema versioning for the generated CONNECTION config
+// (`gaia.config.js`, project + home). Decoupled from the npm package semver —
+// the schema version bumps only when the config SHAPE changes, not every
+// release. Every generated connection config carries a machine-readable header
+// comment `// @gaia-schema-version <N>` (the source of truth for the upgrade
+// decision, read by regex so `gaia upgrade` NEVER executes a possibly
+// side-effecting config module) and a `schema_version: <N>` field for
+// programmatic reads.
+/** The header marker prepended to every generated connection config. */
+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.
+ */
+export const CONNECTION_MIGRATIONS = [
+// { from: 1, to: 2, description: 'add site.jsonapi_prefix default', apply: (t) => … },
+];
+/** The current connection-config schema version — single source of truth. */
+export const GAIA_CONFIG_SCHEMA_VERSION = CONNECTION_MIGRATIONS.at(-1)?.to ?? 1;
+/** Parse the `@gaia-schema-version` marker from config text; `0` when absent. */
+export function schemaVersionOf(text) {
+    const m = MARKER_RE.exec(text);
+    return m ? Number.parseInt(m[1], 10) : 0;
+}
+/**
+ * Read the schema version from a connection config FILE by regex (sync, never
+ * executes the module). `0` when the file is absent, unreadable, or carries no
+ * marker (legacy / hand-authored).
+ */
+export function readConfigSchemaVersion(path) {
+    try {
+        return schemaVersionOf(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return 0;
+    }
+}
+/** Strip a leading `// @gaia-schema-version <N>` header line, if present. */
+export function stripVersionHeader(text) {
+    return text.replace(HEADER_LINE_RE, '');
+}
+/** Prepend (replacing any existing) a `// @gaia-schema-version <N>` header. */
+export function stampVersion(text, version) {
+    return `// @gaia-schema-version ${version}\n${stripVersionHeader(text)}`;
+}
+/**
+ * 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).
+ * An empty chain is valid iff `current === 1`. Throws with an actionable message.
+ */
+export function assertContiguous(chain, current = GAIA_CONFIG_SCHEMA_VERSION) {
+    let prev = 1;
+    chain.forEach((m, i) => {
+        if (m.to !== m.from + 1) {
+            throw new Error(`migration[${i}]: to (${m.to}) must equal from+1 (${m.from + 1})`);
+        }
+        const expectedFrom = i === 0 ? 1 : prev;
+        if (m.from !== expectedFrom) {
+            throw new Error(`migration[${i}]: from (${m.from}) must equal ${expectedFrom} (no gaps; chain starts at v1)`);
+        }
+        prev = m.to;
+    });
+    const end = chain.at(-1)?.to ?? 1;
+    if (end !== current) {
+        throw new Error(`migration chain ends at v${end}, expected CURRENT v${current}`);
+    }
+}
+/**
+ * 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.
+ */
+export function applyMigrations(text, from, to, chain = CONNECTION_MIGRATIONS) {
+    let cur = from;
+    let out = text;
+    while (cur < to) {
+        const step = chain.find((m) => m.from === cur);
+        if (step === undefined) {
+            throw new Error(`no migration from v${cur} (chain incomplete)`);
+        }
+        out = step.apply(out);
+        cur = step.to;
+    }
+    return out;
+}

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

@@ -0,0 +1,34 @@
+import { type GaiaRemote } from '@gaia-ai/core';
+import type { Command } from 'commander';
+export interface GatherResult {
+    range: string;
+    resolved: Array<{
+        identifier: string;
+        uuid: string;
+        title: string;
+    }>;
+    unresolved: string[];
+}
+/** Deduped GAIA-nnn from a git log, in first-seen order. */
+export declare function parseIdentifiers(gitLog: string): string[];
+/**
+ * Compute the release batch from a git-log delta: parse GAIA-nnn identifiers and
+ * resolve each to a ticket. Unresolved identifiers are reported, never fatal
+ * (the resolver returning null is not an error) — GAIA-153 AC-2.
+ */
+export declare function gatherBatch(opts: {
+    sinceRef: string;
+    toRef: string;
+    gitLog: string;
+    resolve: (id: string) => Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
+}): Promise<GatherResult>;
+/**
+ * Register the `gaia deployment` command group. `tickets` computes the release's
+ * tickets (git-log identifier parse + resolve over the given range) and prints
+ * them as JSON — pure compute + report, it does not write `referenced_tickets`
+ * (the prepare-deployment skill does, via the documented dropsh path).
+ */
+export declare function registerDeployment(program: Command, resolveRemote: () => Promise<GaiaRemote>, resolveProject: () => Promise<string>, cwd: () => string): void;

package/dist/src/cli/deployment.js

@@ -0,0 +1,63 @@
+import { exec } from '@gaia-ai/core';
+/** Deduped GAIA-nnn from a git log, in first-seen order. */
+export function parseIdentifiers(gitLog) {
+    const seen = new Set();
+    const out = [];
+    for (const m of gitLog.matchAll(/\bGAIA-\d+\b/g)) {
+        if (!seen.has(m[0])) {
+            seen.add(m[0]);
+            out.push(m[0]);
+        }
+    }
+    return out;
+}
+/**
+ * Compute the release batch from a git-log delta: parse GAIA-nnn identifiers and
+ * resolve each to a ticket. Unresolved identifiers are reported, never fatal
+ * (the resolver returning null is not an error) — GAIA-153 AC-2.
+ */
+export async function gatherBatch(opts) {
+    const resolved = [];
+    const unresolved = [];
+    for (const identifier of parseIdentifiers(opts.gitLog)) {
+        const hit = await opts.resolve(identifier);
+        if (hit) {
+            resolved.push({ identifier, ...hit });
+        }
+        else {
+            unresolved.push(identifier);
+        }
+    }
+    return { range: `${opts.sinceRef}..${opts.toRef}`, resolved, unresolved };
+}
+/**
+ * Register the `gaia deployment` command group. `tickets` computes the release's
+ * tickets (git-log identifier parse + resolve over the given range) and prints
+ * them as JSON — pure compute + report, it does not write `referenced_tickets`
+ * (the prepare-deployment skill does, via the documented dropsh path).
+ */
+export function registerDeployment(program, resolveRemote, resolveProject, cwd) {
+    const dep = program
+        .command('deployment')
+        .description('release / deployment helpers');
+    dep
+        .command('tickets')
+        .description("the release's tickets (git-log identifier parse + resolve over a range) as JSON")
+        .requiredOption('--since <ref>', "the env's currently-deployed ref (git range start)")
+        .requiredOption('--to <ref>', 'the post-merge env branch tip (git range end)')
+        .action(async (opts) => {
+        // Prefix each commit with a record separator (%x1e) so one commit's body
+        // cannot run into the next commit's header line; the identifier parse is
+        // separator-agnostic, but the boundary keeps the log unambiguous.
+        const gitLog = await exec('git', ['log', '--format=%x1e%H %s%n%b', `${opts.since}..${opts.to}`], { cwd: cwd() });
+        const remote = await resolveRemote();
+        const project = await resolveProject();
+        const result = await gatherBatch({
+            sinceRef: opts.since,
+            toRef: opts.to,
+            gitLog,
+            resolve: (id) => remote.resolveTicketByIdentifier(project, id),
+        });
+        console.log(JSON.stringify(result));
+    });
+}

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

@@ -1,3 +1,6 @@
+import { type MachineContext, machineContextPath, readMachineContext } from '@gaia-ai/core';
+export type { MachineContext };
+export { machineContextPath, readMachineContext };
 export interface InitInputs {
     baseUrl: string;
     project: string;
@@ -21,19 +24,6 @@ export interface ScaffoldResult {
     wroteCommitted: boolean;
     machine: MachineContextResult;
 }
-/**
- * The user-global machine context: a plain importable module carrying the
- * developer's machine identity and connection (incl. the OAuth client secret).
- * Committed configs import it to compose machine_id and read
- * base_url / client_id / client_secret. Gitignored, user-only (chmod 0600).
- */
-export interface MachineContext {
-    machine_id: string;
-    user_id: string;
-    base_url: string;
-    client_id: string;
-    client_secret: string;
-}
 export interface MachineContextOptions {
     path: string;
     userId: string;
@@ -48,35 +38,43 @@ export interface MachineContextResult {
     filledKeys: string[];
 }
 /**
- * The committed, structural conductor config. `project` is the only per-repo
- * value and is baked in here; connection + identity (incl. the secret) come from
- * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
- * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
- * optional, gitignored conductor.config.local.js beside this file may override
- * any field — it is loaded if present but never created by `gaia conductor init`.
+ * The committed, structural ENGINE conductor config (GAIA-201). It carries the
+ * engine wiring only — remote/executor/agent/workspace + `machine_id`
+ * composition — and NO `site`/`plugins`, which now live in the sibling
+ * connection config `gaia.config.js`. Connection + identity (incl. the secret)
+ * come from the user-global machine context (`~/.gaia/machine.config.js`);
+ * `machine_id` is composed as `${user_id}-${machine_id}-${project}`.
  */
 export declare function renderCommittedConfig(inputs: Pick<InitInputs, 'project'>): string;
+/**
+ * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
+ * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
+ * conductor's auth. Reads base_url + client credentials from the user-global
+ * machine context (`~/.gaia/machine.config.js`) and declares the session
+ * (default) + pm oauth2 profiles.
+ */
+export declare function renderGaiaConfig(): string;
 /** The user-global machine context module: identity + connection (incl. secret). */
 export declare function renderMachineContext(ctx: MachineContext): string;
-/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
-export declare function machineContextPath(): string;
-/** Import an existing context module's default export, or {} if absent/broken. */
-export declare function readMachineContext(path: string): Promise<Partial<MachineContext>>;
 /**
  * Create-if-missing / fill-only-missing the user-global machine context.
  * Existing values always win; only absent/blank keys are filled. machine_id
- * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
- * The file is written user-only (chmod 0600) since it holds the client secret.
+ * defaults to hostname(). Written user-only (chmod 0600) since it holds the
+ * client secret.
  */
 export declare function scaffoldMachineContext(opts: MachineContextOptions): Promise<MachineContextResult>;
+/** Write the sibling connection config `gaia.config.js` next to the engine
+ *  config. Created only if missing (unless `force`). Returns its path + whether
+ *  it was written. */
+export declare function scaffoldGaiaConfig(engineConfigPath: string, force: boolean): {
+    path: string;
+    wrote: boolean;
+};
 /**
- * Scaffold the two conductor config files: the committed conductor.config.js
- * (created only if missing — never overwritten unless `force`) and the
- * user-global machine context (create-if-missing / fill-only-missing). The
- * optional per-project conductor.config.local.js is NOT generated.
- *
- * `skipMachine` writes the committed config only (project-only setup); its
- * mirror `skipCommitted` writes the machine context only (machine-only
- * onboarding, no repo). Setting both is a no-op.
+ * Scaffold the committed ENGINE conductor.config.js (created only if missing —
+ * never overwritten unless `force`) and the user-global machine context
+ * (create-if-missing / fill-only-missing). The connection config is scaffolded
+ * separately by `scaffoldGaiaConfig`. `skipMachine` writes the committed config
+ * only; `skipCommitted` writes the machine context only.
  */
 export declare function scaffold(inputs: InitInputs, opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/src/cli/init.js

@@ -1,50 +1,51 @@
 import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
 import { hostname } from 'node:os';
 import { dirname, join } from 'node:path';
-import { pathToFileURL } from 'node:url';
+import { machineContextPath, readMachineContext, } from '@gaia-ai/core';
+import { GAIA_CONFIG_SCHEMA_VERSION } from './config-schema.js';
+export { machineContextPath, readMachineContext };
 /** JS single-quoted string literal for a trusted, simple value. */
 function q(value) {
     return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
 }
 /**
- * The committed, structural conductor config. `project` is the only per-repo
- * value and is baked in here; connection + identity (incl. the secret) come from
- * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
- * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
- * optional, gitignored conductor.config.local.js beside this file may override
- * any field — it is loaded if present but never created by `gaia conductor init`.
+ * The committed, structural ENGINE conductor config (GAIA-201). It carries the
+ * engine wiring only — remote/executor/agent/workspace + `machine_id`
+ * composition — and NO `site`/`plugins`, which now live in the sibling
+ * connection config `gaia.config.js`. Connection + identity (incl. the secret)
+ * come from the user-global machine context (`~/.gaia/machine.config.js`);
+ * `machine_id` is composed as `${user_id}-${machine_id}-${project}`.
  */
 export function renderCommittedConfig(inputs) {
-    return `// Canonical GAIA conductor config — committed. Connection + identity come from
-// your user-global machine context (~/.config/conductor/conductor.config.machine.js:
+    return `// Canonical GAIA conductor ENGINE config — committed. Connection + identity
+// come from your user-global machine context (~/.gaia/machine.config.js:
 // { machine_id, user_id, base_url, client_id, client_secret }); machine_id is
 // composed here as \`\${user_id}-\${machine_id}-\${project}\`. \`project\` is the only
-// per-repo value and is baked in below. The client_secret is read from the
-// machine context (gitignored, user-only) — never committed here.
+// per-repo value and is baked in below. This file is ENGINE-ONLY (GAIA-201):
+// it has NO \`site\` and NO auth \`plugins\` — those live in the sibling
+// ./.gaia/gaia.config.js (the connection config that ui + dropsh + this
+// conductor's auth all read).
 //
-// IMPORT-FREE (GAIA-78): the plugin slots + plugins[] are \`{ plugin, with }\`
-// descriptors naming the REAL published package (\`@gaia-ai/plugin-*\`,
-// \`@dropsh/plugin-*\`), not \`import\`ed constructors. loadConductorConfig
-// resolves each name ESLint-style (config dir → cwd → conductor install), so
-// config load never depends on a \`node_modules/@gaia-ai\` symlink beside this
-// file. Each plugin package default-exports its factory, so the resolver's
-// auto-pick needs no \`export:\` here — EXCEPT the \`@gaia-ai/gaia/plugins\` host
-// barrel (many exports → \`export: 'drupalRemote'\`) and the merged herdr
-// workspace slot (\`@gaia-ai/plugin-herdr\` default-exports the executor, so the
-// workspace names \`export: 'herdrWorkspace'\` — GAIA-139).
+// 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).
 
 // The user-global machine context: identity + connection (incl. secret), shared
 // by every project on this machine. Never committed.
 async function loadMachine() {
   try {
-    return (await import(\`\${process.env.HOME}/.config/conductor/conductor.config.machine.js\`)).default ?? {};
+    return (await import(\`\${process.env.HOME}/.gaia/machine.config.js\`)).default ?? {};
   } catch {}
   return {};
 }
 
 // OPTIONAL per-project override — create conductor.config.local.js beside this
-// file to override any field (machine_id, base_url, model, …). It is loaded only
-// if present and is NOT created by \`gaia conductor init\`.
+// file to override any field (machine_id, model, …). Loaded only if present and
+// NOT created by \`gaia conductor init\`.
 async function loadLocal() {
   try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
   return {};
@@ -53,47 +54,74 @@ async function loadLocal() {
 const machine = await loadMachine();
 const local = await loadLocal();
 const project = local.project ?? ${q(inputs.project)};
-const baseUrl = local.base_url ?? machine.base_url;
-const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
-const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
 const composedMachineId =
   machine.user_id && machine.machine_id
     ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
     : undefined;
 
 export default {
-  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
   project,
   machine_id: local.machine_id ?? composedMachineId,
   states: ['spec', 'diagnose', 'coding', 'review'],
   max_parallel: 5,
-  // Lifecycle hooks are executor-owned (GAIA-84): the executor invokes each
-  // best-effort (logs loudly + continues, never aborts a run), so they live at
-  // the config top level — NOT on a plugin descriptor's \`with.hooks\`.
+  // 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' },
-  // No hard-wired diff pane for review: the review diff surface is hunk
-  // (GAIA-55) — agent-driven + opt-in in the human's interactive pane, not an
-  // executor-forced git-diff pane. Clicking a changed file in that hunk pane
-  // opens it editable in a spiceedit overlay (see conductor/README.md).
   executor: { plugin: '@gaia-ai/plugin-herdr' },
   agent: {
     plugin: '@gaia-ai/plugin-claude',
     with: { model: local.model ?? 'claude-opus-4-8' },
   },
-  // GAIA-139: the herdr workspace ships in @gaia-ai/plugin-herdr now (the
-  // separate plugin-herdr-workspace was merged in). That package default-exports
-  // the EXECUTOR, so the workspace slot must name export: 'herdrWorkspace'.
+  // GAIA-139: the herdr workspace ships in @gaia-ai/plugin-herdr, which
+  // default-exports the EXECUTOR — so the workspace slot names export: 'herdrWorkspace'.
   workspace: {
     plugin: '@gaia-ai/plugin-herdr',
     export: 'herdrWorkspace',
   },
-  // oauth2 is a real dep of the host (npm installs it alongside @gaia-ai/gaia).
-  // NOTE: plugins[] is consumed by DROPSH, which reloads this config with its OWN
-  // resolver (\`export ?? 'default'\`, no sole-function auto-pick) on every
-  // \`gaia dropsh …\` command. @dropsh/plugin-oauth2 has no default export, so
-  // these entries MUST name \`export: 'oauth2Plugin'\` — unlike the four conductor
-  // slots above, which the conductor resolves and auto-picks.
+};
+`;
+}
+/**
+ * The committed CONNECTION config `./.gaia/gaia.config.js` (GAIA-201). A
+ * dropsh-shaped `{ site, plugins }` read by `gaia ui`, `gaia dropsh`, and the
+ * conductor's auth. Reads base_url + client credentials from the user-global
+ * machine context (`~/.gaia/machine.config.js`) and declares the session
+ * (default) + pm oauth2 profiles.
+ */
+export function renderGaiaConfig() {
+    return `// @gaia-schema-version ${GAIA_CONFIG_SCHEMA_VERSION}
+// Canonical GAIA CONNECTION config — committed (GAIA-201). A dropsh-shaped
+// { site, plugins } read by 'gaia ui', 'gaia dropsh', and this conductor's auth.
+// Connection + credentials come from your user-global machine context
+// (~/.gaia/machine.config.js). The engine wiring lives in the sibling
+// conductor.config.js (engine-only).
+//
+// plugins[] is consumed by DROPSH, whose resolver has no sole-function
+// auto-pick, so @dropsh/plugin-oauth2 entries MUST name export: 'oauth2Plugin'.
+async function loadMachine() {
+  try {
+    return (await import(\`\${process.env.HOME}/.gaia/machine.config.js\`)).default ?? {};
+  } catch {}
+  return {};
+}
+
+async function loadLocal() {
+  try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
+  return {};
+}
+
+const machine = await loadMachine();
+const local = await loadLocal();
+const baseUrl = local.base_url ?? machine.base_url;
+const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
+const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
+
+export default {
+  // GAIA-216: the connection-config schema version — kept in sync with the
+  // header marker above so \`gaia upgrade\` can migrate a stale-shape config.
+  schema_version: ${GAIA_CONFIG_SCHEMA_VERSION},
+  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
   plugins: [
     {
       plugin: '@dropsh/plugin-oauth2',
@@ -126,12 +154,12 @@ export default {
 }
 /** The user-global machine context module: identity + connection (incl. secret). */
 export function renderMachineContext(ctx) {
-    return `// User-global conductor context — gitignored, user-only (chmod 0600), never
+    return `// User-global GAIA machine context — gitignored, user-only (chmod 0600), never
 // committed. A plain importable module holding your machine identity +
-// connection, incl. the OAuth client secret. Committed conductor.config.js files
-// import this to compose machine_id (\`\${user_id}-\${machine_id}-\${project}\`) and
-// read base_url / client_id / client_secret. Created and gap-filled by
-// \`gaia conductor init\`; existing values are never overwritten.
+// connection, incl. the OAuth client secret. The engine conductor.config.js
+// composes machine_id (\`\${user_id}-\${machine_id}-\${project}\`) from it; the
+// connection gaia.config.js reads base_url / client_id / client_secret. Created
+// and gap-filled by \`gaia conductor init\`; existing values are never overwritten.
 export default {
   machine_id: ${q(ctx.machine_id)},
   user_id: ${q(ctx.user_id)},
@@ -141,31 +169,11 @@ export default {
 };
 `;
 }
-/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
-export function machineContextPath() {
-    return join(process.env.HOME ?? '', '.config', 'conductor', 'conductor.config.machine.js');
-}
-/** Import an existing context module's default export, or {} if absent/broken. */
-export async function readMachineContext(path) {
-    if (!existsSync(path))
-        return {};
-    try {
-        // Cache-bust so a re-render within one process re-reads fresh.
-        const mod = await import(`${pathToFileURL(path).href}?t=${Date.now()}`);
-        const raw = mod.default;
-        return raw && typeof raw === 'object'
-            ? raw
-            : {};
-    }
-    catch {
-        return {};
-    }
-}
 /**
  * Create-if-missing / fill-only-missing the user-global machine context.
  * Existing values always win; only absent/blank keys are filled. machine_id
- * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
- * The file is written user-only (chmod 0600) since it holds the client secret.
+ * defaults to hostname(). Written user-only (chmod 0600) since it holds the
+ * client secret.
  */
 export async function scaffoldMachineContext(opts) {
     const existing = await readMachineContext(opts.path);
@@ -196,20 +204,28 @@ export async function scaffoldMachineContext(opts) {
         mkdirSync(dirname(opts.path), { recursive: true });
         writeFileSync(opts.path, renderMachineContext(merged), 'utf8');
     }
-    // Always tighten perms — the file holds a secret.
     if (existsSync(opts.path))
         chmodSync(opts.path, 0o600);
     return { path: opts.path, created, filledKeys };
 }
+/** Write the sibling connection config `gaia.config.js` next to the engine
+ *  config. Created only if missing (unless `force`). Returns its path + whether
+ *  it was written. */
+export function scaffoldGaiaConfig(engineConfigPath, force) {
+    const path = join(dirname(engineConfigPath), 'gaia.config.js');
+    mkdirSync(dirname(path), { recursive: true });
+    if (!existsSync(path) || force) {
+        writeFileSync(path, renderGaiaConfig(), 'utf8');
+        return { path, wrote: true };
+    }
+    return { path, wrote: false };
+}
 /**
- * Scaffold the two conductor config files: the committed conductor.config.js
- * (created only if missing — never overwritten unless `force`) and the
- * user-global machine context (create-if-missing / fill-only-missing). The
- * optional per-project conductor.config.local.js is NOT generated.
- *
- * `skipMachine` writes the committed config only (project-only setup); its
- * mirror `skipCommitted` writes the machine context only (machine-only
- * onboarding, no repo). Setting both is a no-op.
+ * Scaffold the committed ENGINE conductor.config.js (created only if missing —
+ * never overwritten unless `force`) and the user-global machine context
+ * (create-if-missing / fill-only-missing). The connection config is scaffolded
+ * separately by `scaffoldGaiaConfig`. `skipMachine` writes the committed config
+ * only; `skipCommitted` writes the machine context only.
  */
 export async function scaffold(inputs, opts) {
     const committedPath = opts.configPath;

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

@@ -0,0 +1,38 @@
+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;
+}
+/** 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;
+/** Run the migration. Pure w.r.t. injected `cwd`/`home`; `dryRun` suppresses writes. */
+export declare function runUpgrade(opts?: {
+    cwd?: string;
+    home?: string;
+    dryRun?: boolean;
+}): UpgradeReport;
+export {};