@gaia-ai/conductor 0.6.0 → 0.6.2

package/dist/src/commands/conductor.js

@@ -1,17 +1,15 @@
 import { existsSync } from 'node:fs';
 import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { CommandRunner, createLogger, exec, loadGaiaConfig, machineContextPath, readMachineContext, resolveConfigPath, setDefaultCommandRunner, } from '@gaia-ai/core';
-import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+import { CommandRunner, createLogger, exec, getRegisteredConductor, listRegisteredConductors, loadGaiaConfig, machineContextPath, readMachineContext, registerConductor, removeConductor, resolveConfigPath, setDefaultCommandRunner, } from '@gaia-ai/core';
 import { Command } from 'commander';
 import { authStatus } from 'dropsh';
-import * as conductorRegistry from '../cli/conductor-registry.js';
-import { registerDeployment } from '../cli/deployment.js';
-import { scaffold, scaffoldGaiaConfig } from '../cli/init.js';
+import { scaffold } from '../cli/init.js';
 import { runUpgrade } from '../cli/upgrade.js';
 import { fetchUpdateNotice, printVersionLine } from '../cli/version-check.js';
 import { composeConductorConfig, loadConductorConfig } from '../config.js';
 import { Conductor } from '../core/conductor.js';
+import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '../plugins/plugins.js';
 /** Default host bases for connection/plugin resolution when none is injected. */
 function defaultHost() {
     return { resolveBases: [import.meta.url, `${process.cwd()}/`] };
@@ -64,7 +62,7 @@ function loggerFor(checkoutRoot, log = {}) {
     setDefaultCommandRunner(new CommandRunner(logger));
     return logger;
 }
-// --- herdr host (untested: shells out to herdr) ---------------------------
+// --- herdr host (shells out to herdr; injectable via deps.herdr) -----------
 export function parseHerdrJson(output, command) {
     try {
         return JSON.parse(output);
@@ -100,6 +98,14 @@ async function killViaHerdr(label) {
         await exec('herdr', ['workspace', 'close', ws.workspace_id]);
     }
 }
+/** The production host: the real `herdr` binary. */
+export const realHerdrHost = {
+    spawn: spawnViaHerdr,
+    kill: killViaHerdr,
+};
+function herdrHostOf(deps) {
+    return deps.herdr ?? realHerdrHost;
+}
 // --- ls/status freshness ----------------------------------------------------
 const DEFAULT_FRESH_S = 120;
 function freshnessThresholdS(config) {
@@ -119,7 +125,7 @@ function classify(hub, freshS) {
     return fresh ? 'running' : 'wedged';
 }
 async function buildLsRows(remote, config, onlyId) {
-    const entries = await conductorRegistry.list();
+    const entries = await listRegisteredConductors();
     let hub = [];
     try {
         hub = await remote.listConductors('me');
@@ -249,7 +255,7 @@ async function cmdStartBody(deps, log) {
         return;
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
-    const existing = await conductorRegistry.get(id);
+    const existing = await getRegisteredConductor(id);
     if (existing) {
         const hubStatus = await remote.getConductorStatus(id);
         if (hubStatus !== null && hubStatus !== 'offline') {
@@ -258,7 +264,7 @@ async function cmdStartBody(deps, log) {
         }
     }
     const handle = `gaia-conductor:${id}`;
-    await conductorRegistry.register({
+    await registerConductor({
         id,
         path: checkoutRoot,
         project: config.project,
@@ -274,7 +280,7 @@ async function cmdStartBody(deps, log) {
         .join(' ');
     const fgCmd = `GAIA_CONDUCTOR_LOG=file gaia conductor ${fgFlags} start --foreground`.replace(/\s+/g, ' ');
     try {
-        await spawnViaHerdr(handle, checkoutRoot, fgCmd);
+        await herdrHostOf(deps).spawn(handle, checkoutRoot, fgCmd);
         logger.info({ id, handle }, 'started conductor via herdr');
     }
     catch (err) {
@@ -287,9 +293,9 @@ async function cmdStop(deps, now) {
     const remote = await resolveRemote(deps, config);
     const id = conductorIdOf(config);
     if (now) {
-        const entry = await conductorRegistry.get(id);
+        const entry = await getRegisteredConductor(id);
         if (entry && entry.host === 'herdr') {
-            await killViaHerdr(entry.handle);
+            await herdrHostOf(deps).kill(entry.handle);
             console.log(`hard-stopped conductor ${id} (${entry.handle})`);
         }
         else {
@@ -297,9 +303,9 @@ async function cmdStop(deps, now) {
         }
         return;
     }
-    const entry = await conductorRegistry.get(id);
+    const entry = await getRegisteredConductor(id);
     if (entry && entry.host === 'herdr') {
-        await killViaHerdr(entry.handle);
+        await herdrHostOf(deps).kill(entry.handle);
     }
     await remote.setConductorStatus(id, 'offline');
     console.log(`stopped conductor ${id} (offline)`);
@@ -320,7 +326,7 @@ async function cmdStatus(deps) {
 async function cmdRm(deps) {
     const config = await resolveConfig(deps);
     const id = conductorIdOf(config);
-    await conductorRegistry.remove(id);
+    await removeConductor(id);
     console.log(`removed conductor ${id} from registry`);
 }
 /** ls may run without a config file; best-effort load. */
@@ -516,15 +522,11 @@ function registerInit(conductor) {
             skipMachine: !onboarding,
             skipCommitted: !hasProject,
         });
-        // Scaffold the sibling connection config (project-local gaia.config.js)
-        // next to the engine config when setting up a repo.
-        let wroteConnection = false;
-        let connectionPath = '';
-        if (hasProject) {
-            const conn = scaffoldGaiaConfig(opts.config, opts.force);
-            wroteConnection = conn.wrote;
-            connectionPath = conn.path;
-        }
+        // GAIA-218: `conductor init` writes the ENGINE config only. It no longer
+        // scaffolds a project-local `gaia.config.js` — the global
+        // `~/.gaia/gaia.config.js` (seeded by the reachability step below) is the
+        // default connection every repo inherits; a project override is opt-in
+        // via `gaia upgrade`.
         if (!onboarding) {
             console.log(`machine context found (${machinePath}) → setting up project only`);
             if (typeof existing.base_url !== 'string' ||
@@ -545,20 +547,19 @@ function registerInit(conductor) {
             console.log(res.wroteCommitted
                 ? `wrote ${res.committedPath} (engine)`
                 : `kept ${res.committedPath} (exists — pass --force to replace)`);
-            console.log(wroteConnection
-                ? `wrote ${connectionPath} (connection)`
-                : `kept ${connectionPath} (exists — pass --force to replace)`);
-            // GAIA-216: make the split-config seed reachable from `init` itself —
-            // migrate a legacy machine context and seed the home connection config
+            // GAIA-216/218: make the split-config seed reachable from `init` itself
+            // — migrate a legacy machine context and seed the HOME connection config
             // so an install can never be left with an engine config and no
-            // connection config. Idempotent: a fresh init reports these as kept.
-            // `home` is derived from the machine-context path (canonical
-            // `<home>/.gaia/machine.config.js`) so the home-side steps target the
-            // same home the context lives in — real home in production, isolated
-            // when `--machine-path` overrides it.
+            // connection config. `projectConnection: 'skip'` keeps `init` from
+            // writing a project override (the global connection is the default;
+            // overrides are opt-in via `gaia upgrade`). Idempotent: a fresh init
+            // reports these as kept. `home` is derived from the machine-context path
+            // (canonical `<home>/.gaia/machine.config.js`) so the home-side steps
+            // target the same home the context lives in.
             const reach = runUpgrade({
                 cwd: dirname(dirname(opts.config)),
                 home: dirname(dirname(machinePath)),
+                projectConnection: 'skip',
             });
             for (const line of reach.actions)
                 console.log(line);
@@ -577,22 +578,15 @@ function registerInit(conductor) {
             '  gaia dropsh auth status   # both profiles present');
     });
 }
-/** The `conductor` command plugin the host mounts (GAIA-201). It also registers
- *  the `gaia deployment` batch helper (conductor-scoped: needs remote + project). */
+/** The `conductor` command plugin the host mounts (GAIA-201). GAIA-224
+ *  (Finding 7): the `gaia deployment` batch helper is no longer registered here —
+ *  it is its own command addon, `@gaia-ai/addon-deployment`. */
 const conductorCommandPlugin = {
     kind: 'command',
     name: 'conductor',
     describe: 'node-agent lifecycle + local registry',
     register(program, host) {
-        const deps = { host };
-        program.addCommand(createConductorCommand(deps));
-        registerDeployment(program, async () => {
-            const config = await resolveConfig(deps);
-            return resolveRemote(deps, config);
-        }, async () => {
-            const config = await resolveConfig(deps);
-            return config.project;
-        }, () => process.cwd());
+        program.addCommand(createConductorCommand({ host }));
     },
 };
 export default conductorCommandPlugin;
@@ -604,13 +598,6 @@ export function buildConductorProgram(deps = {}) {
     const program = new Command();
     program.name('gaia').description('GAIA conductor + client CLI');
     program.addCommand(createConductorCommand(deps));
-    registerDeployment(program, async () => {
-        const config = await resolveConfig(deps);
-        return resolveRemote(deps, config);
-    }, async () => {
-        const config = await resolveConfig(deps);
-        return config.project;
-    }, () => process.cwd());
     return program;
 }
 /** Parse argv against the conductor program (test entry). */

package/dist/src/config.d.ts

@@ -1,4 +1,6 @@
-import { type AgentCandidate, type ConductorEngineConfig, type ConductorFileConfig, type GaiaConnectionConfig } from '@gaia-ai/core';
+import { type GaiaConnectionConfig } from '@gaia-ai/core';
+import type { AgentCandidate } from './plugins/plugins.js';
+import type { ConductorEngineConfig, ConductorFileConfig } from './types.js';
 export { findGaiaDir, resolveConfigPath, } from '@gaia-ai/core';
 /**
  * Default agent prompt - the project instruction contract. One run works EXACTLY one state;
@@ -87,3 +89,15 @@ export declare function listConductorConfigFiles(gaiaDir: string): string[];
  * `substates:`/other key containing "states" is not matched.
  */
 export declare function stripStatesFromConfigSource(source: string): string;
+/**
+ * Strip the `site:` and `plugins:` properties from an engine config's
+ * `export default { … }` (with their leading comment/whitespace), plus the
+ * now-orphaned connection preamble consts. Returns the rewritten source and the
+ * list of object keys removed (`[]` — source returned unchanged — when there is
+ * nothing connection-related to remove). remote/executor/agent/workspace/hooks/
+ * project/machine_id/loadLocal are left intact.
+ */
+export declare function stripLegacyConnectionFromConfigSource(source: string): {
+    text: string;
+    removed: string[];
+};

package/dist/src/config.js

@@ -1,7 +1,8 @@
 import { readdirSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { discoverAddons, emptyContributions, resolveConductorSlots, resolveModuleEslintStyle, } from '@gaia-ai/core';
+import { discoverAddons, emptyContributions, findDefaultExportObject, matchDelimiter, resolveConductorSlots, resolveModuleEslintStyle, scanTopLevelProperties, } from '@gaia-ai/core';
+import { narrowConductorContributions } from './plugins/preset.js';
 // GAIA-201: the `.gaia/` walk-up + connection resolution moved to `@gaia-ai/core`
 // (`resolveConfigPath` / `resolveGaiaConfigPath` / `findGaiaDir`). Re-export the
 // engine resolver here so existing conductor callers/tests keep importing it
@@ -40,7 +41,7 @@ export { findGaiaDir, resolveConfigPath, } from '@gaia-ai/core';
  * `qualification` for unclassified tickets).
  */
 export const DEFAULT_AGENT_PROMPT = `You are working ticket {identifier}, current state: {state}. Read the ticket and all comments ` +
-    `(gaia dropsh read gaia_ticket/gaia_ticket/$GAIA_ID --include comments), ` +
+    `(gaia dropsh --format md read gaia_ticket/gaia_ticket/$GAIA_ID --include comments), ` +
     `then read ./WORKFLOW.md and execute only its ordered "State: {state}" section. ` +
     `Do not start or prepare a later state.`;
 function requirePlugin(value, kind) {
@@ -169,6 +170,15 @@ export async function loadConductorConfig(configFile) {
     if (!isRecord(raw)) {
         throw new Error('conductor config default export must be an object');
     }
+    // GAIA-218 (AC-6): the engine config must not carry connection/auth material.
+    // A legacy config still declaring `site`/`plugins` gets exactly ONE actionable
+    // warning naming the file + the offending key(s); the values are never merged
+    // (`ConductorEngineConfig` omits both structurally).
+    const leftover = ['site', 'plugins'].filter((k) => k in raw);
+    if (leftover.length > 0) {
+        console.warn(`warning: ${configPath} declares ${leftover.join('/')} — ignored; ` +
+            'auth/connection belong in the sibling gaia.config.js (GAIA-218)');
+    }
     const config = raw;
     const project = requireNonEmptyString(config.project, 'project');
     // `states` is optional. An empty (or absent) list means the conductor serves
@@ -192,13 +202,18 @@ export async function loadConductorConfig(configFile) {
     // GAIA-215: discover the conductor `addons: []` surface (last-wins singletons,
     // agent candidate list). A pre-existing per-slot descriptor still loads and
     // WINS over a discovered contributor of the same kind (back-compat additive).
-    const discovered = Array.isArray(config.addons)
+    // GAIA-224: `discoverAddons` is surface-AGNOSTIC — it returns opaque
+    // accumulators. This is the single, reviewed narrowing seam where the engine
+    // reinterprets them as its own concrete conductor contributions; the runtime
+    // `.kind` guard inside `resolveConductorSlots` still fails loudly on a
+    // mis-declared contribution.
+    const discovered = narrowConductorContributions(Array.isArray(config.addons)
         ? await discoverAddons(config.addons, 'conductor', [
             pathToFileURL(configPath).href,
             pathToFileURL(`${process.cwd()}/`).href,
             import.meta.url,
         ])
-        : emptyContributions();
+        : emptyContributions());
     const wired = resolveConductorSlots(discovered);
     const remote = config.remote !== undefined
         ? await resolveSlot(config.remote, 'remote', configPath)
@@ -301,3 +316,103 @@ export function listConductorConfigFiles(gaiaDir) {
 export function stripStatesFromConfigSource(source) {
     return source.replace(/\n?[ \t]*(?<![A-Za-z0-9_$])states[ \t]*:[ \t]*\[[^\]]*\][ \t]*,?/g, '');
 }
+// ---------------------------------------------------------------------------
+// GAIA-218 (AC-7): strip legacy connection/auth from an ENGINE config source.
+//
+// Unlike `stripStatesFromConfigSource`'s flat `\[[^\]]*\]` regex (nested-unsafe),
+// this is a balanced-delimiter, comment-aware source transform. The engine
+// config's `plugins: [ … ]` array holds nested `{}` (oauth2 profiles AND
+// `@gaia-ai/addon-essentials`), a sibling `agent: [ … ]` array, and the word
+// "plugins" also appears in comments — so the removal keys on the REAL `site:` /
+// `plugins:` *properties* of the default-export object, scanning each value from
+// its opening delimiter to the matching close while skipping string/comment
+// bytes. It also removes the now-orphaned connection preamble consts
+// (`baseUrl`/`clientId`/`clientSecret`) and a connection-only `loadMachine`
+// (with its `const machine = await loadMachine()`) when they become unreferenced.
+// ---------------------------------------------------------------------------
+// GAIA-230: the scanner primitives themselves now live in `@gaia-ai/core`
+// (`core/src/cli/config-source.ts`) — the kernel needs them for the content-gated
+// legacy connection read, and layer 0 cannot import this package. Imported above.
+/** Count word-boundary occurrences of an identifier in the source. */
+function countIdent(src, name) {
+    const re = new RegExp(`(?<![A-Za-z0-9_$])${name}(?![A-Za-z0-9_$])`, 'g');
+    return (src.match(re) ?? []).length;
+}
+/** Remove a single-line `const <name> = …;` declaration (no-op if absent). */
+function removeConstDecl(src, name) {
+    const re = new RegExp(`^[ \\t]*const ${name}\\b[^\\n]*\\n`, 'm');
+    return src.replace(re, '');
+}
+/** Remove an `[async ]function <name>(…) { … }` declaration (balanced body). */
+function removeFunctionDecl(src, name) {
+    const re = new RegExp(`(?:async[ \\t]+)?function[ \\t]+${name}[ \\t]*\\(`);
+    const m = re.exec(src);
+    if (!m)
+        return src;
+    const braceIdx = src.indexOf('{', m.index);
+    if (braceIdx === -1)
+        return src;
+    const end = matchDelimiter(src, braceIdx);
+    if (end === -1)
+        return src;
+    let e = end + 1;
+    if (src[e] === '\n')
+        e++;
+    return src.slice(0, m.index) + src.slice(e);
+}
+/**
+ * Is `machine` referenced anywhere OTHER than its own `const machine = …;` decl
+ * and inside the `loadMachine` function body? (The body's `…/machine.config.js`
+ * path string must not count as a live reference.) Used to decide whether a
+ * connection-only `loadMachine` has become orphaned.
+ */
+function machineReferencedElsewhere(src) {
+    let probe = removeFunctionDecl(src, 'loadMachine');
+    probe = removeConstDecl(probe, 'machine');
+    return countIdent(probe, 'machine') > 0;
+}
+/** Drop connection preamble that is orphaned once `site`/`plugins` are gone. */
+function removeOrphanedPreamble(src) {
+    let text = src;
+    for (const name of ['baseUrl', 'clientId', 'clientSecret']) {
+        if (countIdent(text, name) <= 1)
+            text = removeConstDecl(text, name);
+    }
+    // A connection-only `loadMachine`: remove `const machine = await loadMachine()`
+    // + the function itself only when `machine` is otherwise unreferenced (so an
+    // engine config that still composes `machine_id` from `machine.user_id` keeps
+    // its loadMachine — the "connection-only" qualifier).
+    if (/\bconst machine\b/.test(text) &&
+        /\bfunction loadMachine\b/.test(text) &&
+        !machineReferencedElsewhere(text)) {
+        text = removeConstDecl(text, 'machine');
+        text = removeFunctionDecl(text, 'loadMachine');
+    }
+    return text;
+}
+/**
+ * Strip the `site:` and `plugins:` properties from an engine config's
+ * `export default { … }` (with their leading comment/whitespace), plus the
+ * now-orphaned connection preamble consts. Returns the rewritten source and the
+ * list of object keys removed (`[]` — source returned unchanged — when there is
+ * nothing connection-related to remove). remote/executor/agent/workspace/hooks/
+ * project/machine_id/loadLocal are left intact.
+ */
+export function stripLegacyConnectionFromConfigSource(source) {
+    const obj = findDefaultExportObject(source);
+    if (!obj)
+        return { text: source, removed: [] };
+    const entries = scanTopLevelProperties(source, obj.bodyStart, obj.bodyEnd);
+    const targets = new Set(['site', 'plugins']);
+    const toRemove = entries.filter((e) => e.key !== undefined && targets.has(e.key));
+    if (toRemove.length === 0)
+        return { text: source, removed: [] };
+    let text = source;
+    for (const e of [...toRemove].sort((a, b) => b.start - a.start)) {
+        text = text.slice(0, e.start) + text.slice(e.end);
+    }
+    text = removeOrphanedPreamble(text);
+    // Report in source order for a stable `site/plugins` message.
+    const removed = ['site', 'plugins'].filter((k) => toRemove.some((e) => e.key === k));
+    return { text, removed };
+}

package/dist/src/contract.d.ts

@@ -0,0 +1,8 @@
+export { type AgentFootprint, emptyAgentFootprint, type GaiaAgent, } from './plugins/agent.js';
+export type { ExecutorCapabilities, GaiaExecutor, HookContext, HookName, SpawnedSession, SpawnRunInput, } from './plugins/executor.js';
+export type { AgentCandidate, AgentPlugin, ExecutorDeps, ExecutorPlugin, RemotePlugin, ResolvedAgent, WorkspacePlugin, } from './plugins/plugins.js';
+export { selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
+export { type ConductorAddonEntry, type ConductorContributions, narrowConductorContributions, type Preset, } from './plugins/preset.js';
+export type { ActiveRun, ClaimedRun, ClaimOptions, ConductorRegistration, ConductorStatus, FinalizableRun, GaiaRemote, RunMetrics, RunWriteAttributes, Ticket, UncleanTicket, } from './plugins/remote.js';
+export type { EnsuredWorkspace, GaiaWorkspace, } from './plugins/workspace.js';
+export type { ConductorEngineConfig, ConductorFileConfig, ConductorSettings, } from './types.js';

package/dist/src/contract.js

@@ -0,0 +1,16 @@
+// GAIA-224 (Finding 6): the CONDUCTOR-SURFACE CONTRACT, exposed as the
+// runtime-light subpath `@gaia-ai/conductor/contract`.
+//
+// This is the module a conductor-surface addon (`addons/remote-drupal`,
+// `addons/workspace-git`, `addons/herdr`, `addons/claude`, …) imports. It carries
+// ONLY the surface interfaces, the config contract, the preset view, and the two
+// tiny runtime helpers (`emptyAgentFootprint`, the `select*` slot selectors) — it
+// imports NO engine, NO commander, NO dropsh runtime. Importing it therefore
+// costs an addon nothing at boot, unlike the package main (`@gaia-ai/conductor`),
+// which pulls the whole run engine + the `conductor` command plugin.
+//
+// The package main re-exports everything here too, so `import type { GaiaRemote }
+// from '@gaia-ai/conductor'` keeps working for type-only consumers.
+export { emptyAgentFootprint, } from './plugins/agent.js';
+export { selectAgent, selectAgents, selectExecutor, selectRemote, selectWorkspace, } from './plugins/plugins.js';
+export { narrowConductorContributions, } from './plugins/preset.js';

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

@@ -1,4 +1,9 @@
-import { type ConductorFileConfig, type ConductorLogger, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace, type ResolvedAgent } from '@gaia-ai/core';
+import { type ConductorLogger } from '@gaia-ai/core';
+import type { GaiaExecutor } from '../plugins/executor.js';
+import { type ResolvedAgent } from '../plugins/plugins.js';
+import type { GaiaRemote } from '../plugins/remote.js';
+import type { GaiaWorkspace } from '../plugins/workspace.js';
+import type { ConductorFileConfig } from '../types.js';
 /**
  * Resolve the environment a run executes in (GAIA-99): parse the ticket's
  * effective env_vars, drop any reserved key (loud warn — key NAME only, never
@@ -66,5 +71,15 @@ export declare class Conductor {
     reap(): Promise<void>;
     private dispatch;
     serve(signal?: AbortSignal): Promise<void>;
+    /**
+     * True once this conductor's own checkout has been removed from disk (its
+     * worktree was reaped while the process kept running). Such a conductor is a
+     * pure liability: it still heartbeats and still claims runs, but every
+     * dispatch fails — no git command and no relative path can resolve from a
+     * deleted directory — so each claim burns one attempt and three of them park
+     * the ticket behind the circuit breaker. Observed as 30 orphans claiming and
+     * failing tickets they could never dispatch.
+     */
+    private checkoutGone;
     private pollLoop;
 }

package/dist/src/core/conductor.js

@@ -1,4 +1,6 @@
-import { conductorId, selectAgent, } from '@gaia-ai/core';
+import { existsSync } from 'node:fs';
+import { conductorId } from '@gaia-ai/core';
+import { selectAgent } from '../plugins/plugins.js';
 function sleep(ms, signal) {
     return new Promise((resolve) => {
         if (signal?.aborted) {
@@ -433,8 +435,28 @@ export class Conductor {
     async serve(signal) {
         await this.pollLoop(signal);
     }
+    /**
+     * True once this conductor's own checkout has been removed from disk (its
+     * worktree was reaped while the process kept running). Such a conductor is a
+     * pure liability: it still heartbeats and still claims runs, but every
+     * dispatch fails — no git command and no relative path can resolve from a
+     * deleted directory — so each claim burns one attempt and three of them park
+     * the ticket behind the circuit breaker. Observed as 30 orphans claiming and
+     * failing tickets they could never dispatch.
+     */
+    checkoutGone() {
+        return !existsSync(this.checkoutRoot);
+    }
     async pollLoop(signal) {
         while (!signal?.aborted) {
+            if (this.checkoutGone()) {
+                // Stop claiming and let the loop end — the process exits and the cron
+                // reaper flips status to offline on lease expiry, same as any crash.
+                // Deliberately NOT an offline write from here: the loop never owns that
+                // transition (see the note at the end of this method).
+                this.logger.error({ conductorId: this.id, workspace: this.checkoutRoot }, 'checkout is gone — stopping conductor instead of claiming runs it cannot dispatch');
+                return;
+            }
             try {
                 await this.tick();
             }

package/dist/src/index.d.ts

@@ -1,9 +1,11 @@
 export type * from '@gaia-ai/core';
+export type { ConductorRegistryEntry } from '@gaia-ai/core';
 export { conductorId } from '@gaia-ai/core';
-export { DrupalGaiaRemote, drupalRemote, FakeGaiaRemote, FakeWorkspace, fakeRemote, fakeWorkspace, GitWorkspace, gitWorkspace, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
-export type { ConductorRegistryEntry } from './cli/conductor-registry.js';
+export { GAIA_CONFIG_SCHEMA_VERSION, readConfigSchemaVersion, } from './cli/config-schema.js';
 export { renderGaiaConfig } from './cli/init.js';
-export { runConnectionUpgrade, runUpgrade, type UpgradeReport, } from './cli/upgrade.js';
+export { type AddonRenameResult, type ConfigSurface, HOST_BARREL_PATHS, migrateAddonNames, migrateAddonNamesInFile, RENAMED_ADDONS, runAddonRenameMigration, } from './cli/migrate-addon-names.js';
+export { hasProjectConnection, type ProjectConnectionChoice, runConnectionUpgrade, runUpgrade, type UpgradeReport, } from './cli/upgrade.js';
 export { default as conductorCommandPlugin, type GaiaCliDeps, runConductorCli, } from './commands/conductor.js';
-export { composeConductorConfig, DEFAULT_AGENT_PROMPT, loadConductorConfig, } from './config.js';
+export { composeConductorConfig, DEFAULT_AGENT_PROMPT, loadConductorConfig, stripLegacyConnectionFromConfigSource, } from './config.js';
+export * from './contract.js';
 export { Conductor } from './core/conductor.js';

package/dist/src/index.js

@@ -1,14 +1,31 @@
 export { conductorId } from '@gaia-ai/core';
-export { DrupalGaiaRemote, drupalRemote, FakeGaiaRemote, FakeWorkspace, fakeRemote, fakeWorkspace, GitWorkspace, gitWorkspace, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+// GAIA-216: the connection-config schema version + its regex reader. GAIA-230:
+// the host's `gaia upgrade` intro prints the `from → to` pair from these.
+export { GAIA_CONFIG_SCHEMA_VERSION, readConfigSchemaVersion, } from './cli/config-schema.js';
 // GAIA-201: the connection-config template, reused by `gaia upgrade` to seed a
 // `gaia.config.js`.
 export { renderGaiaConfig } from './cli/init.js';
+// GAIA-224 (Finding 8b): the addon package-name rename pass `gaia upgrade` runs
+// as its last step (`@gaia-ai/plugin-*` + the deleted `@gaia-ai/core/builtins`
+// and `@gaia-ai/core/plugins` → `@gaia-ai/addon-*`).
+export { HOST_BARREL_PATHS, migrateAddonNames, migrateAddonNamesInFile, RENAMED_ADDONS, runAddonRenameMigration, } from './cli/migrate-addon-names.js';
 // GAIA-216: the seed/migration routine, hoisted from the host so `conductor init`
 // (intra-package) and `gaia upgrade` (host→engine) share one implementation.
-export { runConnectionUpgrade, runUpgrade, } from './cli/upgrade.js';
+export { hasProjectConnection, runConnectionUpgrade, runUpgrade, } from './cli/upgrade.js';
 // GAIA-201: the conductor is now a COMMAND PLUGIN mounted by the `@gaia-ai/gaia`
 // host, not the CLI entrypoint. `main`/`runGaiaCli` are gone; the default export
 // is the `GaiaCommandPlugin`, exposed here as `./commands/conductor` too.
 export { default as conductorCommandPlugin, runConductorCli, } from './commands/conductor.js';
-export { composeConductorConfig, DEFAULT_AGENT_PROMPT, loadConductorConfig, } from './config.js';
+// GAIA-218: the balanced strip is exported for the host/tests + reuse.
+export { composeConductorConfig, DEFAULT_AGENT_PROMPT, loadConductorConfig, stripLegacyConnectionFromConfigSource, } from './config.js';
+// GAIA-224 (Finding 6): this package now OWNS the conductor-surface contract —
+// the interfaces, the config types, the preset view and the slot selectors — and
+// re-exports the whole of it here. The runtime-light subpath
+// `@gaia-ai/conductor/contract` is the one an ADDON should import (this main
+// entry pulls the engine + the command plugin). The built-in IMPLEMENTATIONS it
+// used to re-export from the deleted `@gaia-ai/core/plugins` barrel now live in
+// their own addons (`@gaia-ai/addon-remote-drupal`,
+// `@gaia-ai/addon-workspace-git`, `@gaia-ai/addon-fake`) and are deliberately NOT
+// re-exported: the engine must not edge an addon (acyclic layer rule).
+export * from './contract.js';
 export { Conductor } from './core/conductor.js';

package/dist/src/plugins/agent.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Per-agent effort footprint parsed from that agent's run transcript
+ * (GAIA-132). The metrics are transcript-derived and therefore
+ * **agent-specific** (each agent's transcript has its own format), so parsing
+ * lives behind the agent abstraction (see {@link GaiaAgent.parseFootprint}) —
+ * the conductor stays agent-agnostic and writes the footprint verbatim.
+ * `duration_s` is likewise derived from the transcript (its first→last entry
+ * timestamps), NOT recomputed by the conductor from a re-read `started_at`
+ * (GAIA-151): the log is the single source of the run's wall-clock length, so
+ * there is no timestamp round-trip through JSON:API to mis-parse.
+ */
+export interface AgentFootprint {
+    /** Total tokens across every usage bucket of every assistant turn. */
+    tokens: number;
+    /**
+     * Wall-clock run length in seconds, derived from the transcript's first→last
+     * entry timestamps (GAIA-151). 0 when the transcript has fewer than two
+     * timestamped entries (empty/absent log).
+     */
+    duration_s: number;
+    /** Number of assistant turns in the transcript. */
+    agent_turns: number;
+    /** Number of tool-use calls across all assistant turns. */
+    tool_calls: number;
+    /** Number of user-submitted prompts. */
+    user_prompts: number;
+    /** Total words across those user prompts. */
+    user_prompt_words: number;
+    /** Model of the last assistant turn, when present (informational). */
+    model?: string;
+}
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export declare function emptyAgentFootprint(): AgentFootprint;
+/**
+ * A GAIA agent: the program the conductor runs to work a ticket (e.g. claude).
+ * It knows how it is launched (CLI + model + flags) and where its per-run
+ * transcript/log lives — so the conductor stays agent-agnostic and the CLI can
+ * attach the run log on release without agent-specific knowledge.
+ */
+export interface GaiaAgent {
+    /** Stable id, e.g. 'claude'. */
+    readonly id: string;
+    /**
+     * Build the full agent CLI invocation for a GAIA prompt. With an empty
+     * prompt, returns the bare launch command (no prompt argument).
+     */
+    launchCommand(prompt: string): string;
+    /**
+     * Locate and read this agent's run transcript for a run that executed in
+     * `worktreePath`. MUST return '' (never throw) when nothing is found.
+     */
+    getRunLog(worktreePath: string): Promise<string>;
+    /**
+     * Parse this agent's run transcript (as returned by {@link getRunLog}) into
+     * a footprint of effort metrics (GAIA-132). The transcript format is
+     * agent-specific, so each agent owns its own parser. MUST be tolerant of
+     * blank/partial/absent input (never throw) — an empty log yields
+     * {@link emptyAgentFootprint}.
+     */
+    parseFootprint(log: string): AgentFootprint;
+}

package/dist/src/plugins/agent.js

@@ -0,0 +1,11 @@
+/** An all-zero footprint — the honest result for an empty/absent transcript. */
+export function emptyAgentFootprint() {
+    return {
+        tokens: 0,
+        duration_s: 0,
+        agent_turns: 0,
+        tool_calls: 0,
+        user_prompts: 0,
+        user_prompt_words: 0,
+    };
+}