@gaia-ai/conductor 0.4.3 → 0.4.5

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

@@ -1,4 +1,5 @@
 import { type ConductorFileConfig, type ConductorLogger, type GaiaAgent, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace } from '@gaia-ai/core';
+import { Command } from 'commander';
 /** Test seam: inject any subset of dependencies. */
 export interface GaiaCliDeps {
     remote?: GaiaRemote;
@@ -15,5 +16,6 @@ export declare function parseHerdrJson(output: string, command: string): unknown
  * when unauthenticated.
  */
 export declare function ensureAuthenticated(config: ConductorFileConfig, logger: ConductorLogger): Promise<boolean>;
+export declare function buildProgram(deps: GaiaCliDeps): Command;
 export declare function runGaiaCli(argv: string[], deps?: GaiaCliDeps): Promise<void>;
 export declare function main(argv: string[]): Promise<void>;

package/dist/src/cli/gaia.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { createInterface } from 'node:readline';
 import { fileURLToPath } from 'node:url';
-import { CommandRunner, conductorId, createLogger, exec, setDefaultCommandRunner, } from '@gaia-ai/core';
+import { CommandRunner, createLogger, exec, setDefaultCommandRunner, } from '@gaia-ai/core';
 import { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
 import { Command } from 'commander';
 import { authStatus, buildProgram as buildDropshProgram } from 'dropsh';
@@ -32,13 +32,17 @@ function checkoutRootOf(config) {
     return dirname(config.config_path);
 }
 /**
- * The conductor's stable identity (gaia_conductor.machine_id). The loader
- * always resolves this (config override or hostname+path hash), so lifecycle
- * commands read it here instead of re-deriving the hash — otherwise a pinned
- * machine_id and the CLI's id would diverge.
+ * The conductor's stable identity (gaia_conductor.machine_id). machine_id is
+ * required — the loader (loadConductorConfig) throws without it — so lifecycle
+ * commands read it here, never re-derive. A config not built by the loader that
+ * somehow lacks it fails loudly rather than silently minting a divergent id.
  */
 function conductorIdOf(config) {
-    return config.machine_id ?? conductorId(checkoutRootOf(config));
+    const id = config.machine_id;
+    if (id === undefined || id.trim() === '') {
+        throw new Error('conductor config has no machine_id');
+    }
+    return id;
 }
 /** Read the `conductor`-level --log-level / --log-sink flags from a subcommand. */
 function logOptsOf(cmd) {
@@ -388,9 +392,23 @@ function resolveCliVersion() {
     }
     return '0.0.0';
 }
-function buildProgram(deps) {
+export function buildProgram(deps) {
     const program = new Command();
-    program.name('gaia').description('GAIA conductor + client CLI');
+    program
+        .name('gaia')
+        .description('GAIA conductor + client CLI')
+        .option('--conductor <name>', 'select a named .gaia/<name>.config.js (default: the sole config; env $GAIA_CONDUCTOR)');
+    // GAIA-126: a repo may hold several named .gaia/<stem>.config.js conductors.
+    // resolveConfigPath already honours $GAIA_CONDUCTOR; thread the global
+    // --conductor flag into it (flag wins over env) so every command selects the
+    // named config without per-command wiring. A per-invocation flag beats any
+    // ambient env for this run.
+    program.hook('preAction', () => {
+        const name = program.opts().conductor;
+        if (typeof name === 'string' && name !== '') {
+            process.env.GAIA_CONDUCTOR = name;
+        }
+    });
     const cliVersion = resolveCliVersion();
     program.version(cliVersion); // -V, --version
     program

package/dist/src/config.d.ts

@@ -1,4 +1,4 @@
-import { type ConductorFileConfig } from '@gaia-ai/core';
+import type { ConductorFileConfig } from '@gaia-ai/core';
 /**
  * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
  * the agent must stop instead of running the whole flow in one session. The run
@@ -28,13 +28,17 @@ import { type ConductorFileConfig } from '@gaia-ai/core';
  */
 export declare const DEFAULT_AGENT_PROMPT: string;
 /**
- * Resolve the conductor config path from `cwd`. An explicit `--config`
- * override or `$GAIA_CONDUCTOR_CONFIG` wins verbatim (short-circuit, no
- * filesystem walk). Otherwise walk from `cwd` root-ward (git/eslint style) to
- * the nearest ancestor holding `.gaia/conductor.config.js` and return that
- * absolute path — so any subdirectory of a project/worktree resolves the same
- * config. If none is found up to the filesystem root, throw a clear, actionable
- * error instead of leaking a raw "Cannot find module" from a later import().
+ * Resolve the conductor config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding `*.config.js`
+ *    — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves
+ *      `<gaiaDir>/<name>.config.js` (error listing the stems if absent).
+ *    - No selector: exactly one config → use it (back-compat: the lone
+ *      `conductor.config.js`); many → error naming the stems + the selector.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error
+ *    (never leak a raw "Cannot find module" from a later import()).
  */
-export declare function resolveConfigPath(override?: string, cwd?: string): string;
+export declare function resolveConfigPath(override?: string, cwd?: string, conductorName?: string): string;
 export declare function loadConductorConfig(configFile: string): Promise<ConductorFileConfig>;

package/dist/src/config.js

@@ -1,8 +1,7 @@
-import { existsSync } from 'node:fs';
+import { existsSync, readdirSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { conductorId, } from '@gaia-ai/core';
 /**
  * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
  * the agent must stop instead of running the whole flow in one session. The run
@@ -123,13 +122,19 @@ async function resolveSlot(value, kind, configPath) {
 /**
  * Resolve the `plugins[]` array: descriptor entries are constructed, already-
  * constructed entries pass through. No kind-guard (plugins are not slotted).
+ *
+ * A factory may return one plugin OR an array of plugins — an aggregator built
+ * with dropsh's `composePlugins(a(), b())` returns the flat child list. dropsh's
+ * own `loadConfig` flattens such a nested entry one level; we mirror that here so
+ * `buildProgram({ plugins })` — which reads each entry's hooks/renderers per
+ * top-level element and does NOT recurse — sees every child.
  */
 async function resolvePlugins(raw, configPath) {
     if (!Array.isArray(raw)) {
         return [];
     }
     const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadNamedPlugin(entry, configPath) : entry));
-    return resolved;
+    return resolved.flat();
 }
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
@@ -149,35 +154,70 @@ function optionalPositiveInteger(value, fallback, key) {
     }
     return value;
 }
-/** The conductor config lives at .gaia/conductor.config.js inside a project root. */
-const CONFIG_RELATIVE_PATH = join('.gaia', 'conductor.config.js');
+/** A repo's config files live in this dir, one `<stem>.config.js` per conductor. */
+const GAIA_DIR = '.gaia';
+/** List the `*.config.js` stems in a `.gaia/` dir (e.g. `shop.config.js` → `shop`). */
+function configStems(gaiaDir) {
+    return readdirSync(gaiaDir)
+        .filter((f) => f.endsWith('.config.js'))
+        .map((f) => f.slice(0, -'.config.js'.length))
+        .sort();
+}
 /**
- * Resolve the conductor config path from `cwd`. An explicit `--config`
- * override or `$GAIA_CONDUCTOR_CONFIG` wins verbatim (short-circuit, no
- * filesystem walk). Otherwise walk from `cwd` root-ward (git/eslint style) to
- * the nearest ancestor holding `.gaia/conductor.config.js` and return that
- * absolute path — so any subdirectory of a project/worktree resolves the same
- * config. If none is found up to the filesystem root, throw a clear, actionable
- * error instead of leaking a raw "Cannot find module" from a later import().
+ * Walk from `cwd` root-ward (git/eslint style) to the nearest ancestor whose
+ * `.gaia/` dir holds at least one `*.config.js`; return that `.gaia/` dir, or
+ * `undefined` if none is found up to the filesystem root.
  */
-export function resolveConfigPath(override, cwd = process.cwd()) {
-    const explicit = override ?? process.env.GAIA_CONDUCTOR_CONFIG;
-    if (explicit) {
-        return explicit;
-    }
+function findGaiaDir(cwd) {
     let dir = resolve(cwd);
     for (;;) {
-        const candidate = join(dir, CONFIG_RELATIVE_PATH);
-        if (existsSync(candidate)) {
-            return candidate;
+        const gaiaDir = join(dir, GAIA_DIR);
+        if (existsSync(gaiaDir) && configStems(gaiaDir).length > 0) {
+            return gaiaDir;
         }
         const parent = dirname(dir);
         if (parent === dir) {
-            break;
+            return undefined;
         }
         dir = parent;
     }
-    throw new Error(`no .gaia/conductor.config.js found from ${cwd} upward; run \`gaia init\``);
+}
+/**
+ * Resolve the conductor config path from `cwd`.
+ *
+ * 1. An explicit `--config` / `$GAIA_CONDUCTOR_CONFIG` wins verbatim (no walk).
+ * 2. Otherwise walk root-ward to the nearest `.gaia/` dir holding `*.config.js`
+ *    — so any subdirectory of a project/worktree resolves the same dir.
+ *    - A `--conductor <name>` / `$GAIA_CONDUCTOR` selector resolves
+ *      `<gaiaDir>/<name>.config.js` (error listing the stems if absent).
+ *    - No selector: exactly one config → use it (back-compat: the lone
+ *      `conductor.config.js`); many → error naming the stems + the selector.
+ * 3. No `.gaia/` config anywhere up the tree → an actionable `gaia init` error
+ *    (never leak a raw "Cannot find module" from a later import()).
+ */
+export function resolveConfigPath(override, cwd = process.cwd(), conductorName) {
+    const explicit = override ?? process.env.GAIA_CONDUCTOR_CONFIG;
+    if (explicit) {
+        return explicit;
+    }
+    const gaiaDir = findGaiaDir(cwd);
+    if (gaiaDir === undefined) {
+        throw new Error(`no .gaia/conductor.config.js found from ${cwd} upward; run \`gaia init\``);
+    }
+    const stems = configStems(gaiaDir);
+    const name = conductorName ?? process.env.GAIA_CONDUCTOR;
+    if (name !== undefined && name !== '') {
+        const candidate = join(gaiaDir, `${name}.config.js`);
+        if (!existsSync(candidate)) {
+            throw new Error(`no conductor '${name}' in ${gaiaDir}; available: ${stems.join(', ')}`);
+        }
+        return candidate;
+    }
+    if (stems.length === 1) {
+        return join(gaiaDir, `${stems[0]}.config.js`);
+    }
+    throw new Error(`${stems.length} conductors in ${gaiaDir} (${stems.join(', ')}); ` +
+        'select one with --conductor <name> or $GAIA_CONDUCTOR');
 }
 export async function loadConductorConfig(configFile) {
     const configPath = resolve(configFile);
@@ -194,14 +234,15 @@ export async function loadConductorConfig(configFile) {
         throw new Error('conductor config requires non-empty states');
     }
     const states = config.states.map((state) => requireNonEmptyString(state, 'states'));
-    const checkoutRoot = dirname(configPath);
-    // Resolve the effective machine_id once (config override or hostname+path
-    // hash) so the id is defined in a single place — the CLI lifecycle commands
-    // and registration all read config.machine_id, never re-derive it. The
-    // conductor label defaults to this id (a conductor is identified by it).
-    const machineId = typeof config.machine_id === 'string' && config.machine_id.trim() !== ''
-        ? config.machine_id
-        : conductorId(checkoutRoot);
+    // machine_id is required — the config MUST set it; there is no derived
+    // fallback. The id is defined in a single place (config.machine_id), which
+    // the CLI lifecycle commands and registration all read, never re-derive. The
+    // conductor label defaults to it (a conductor is identified by it). A repo's
+    // committed config composes it from the machine context
+    // (`${user_id}-${machine_id}-${project}`); with several named configs in one
+    // .gaia/ (GAIA-126) each composes its own from its own project, so co-located
+    // conductors get distinct identities with no filename-based fallback.
+    const machineId = requireNonEmptyString(config.machine_id, 'machine_id');
     const label = typeof config.label === 'string' && config.label.trim() !== ''
         ? config.label
         : machineId;

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

@@ -38,27 +38,25 @@ export declare class Conductor {
      * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket that is
      * finished (state=done OR closed) but not yet cleaned. The SAME reconciliation
      * runs on every tick AND standalone as `gaia conductor reap`, and the query is
-     * NOT machine-scoped — so it catches the orphans a live-tick-only path
-     * structurally cannot (RC2/RC3): the conductor was down when the ticket hit
-     * `done`, crashed mid-cleanup, or the ticket's `conductor_id` was reassigned.
-     * A foreign (non-gaia) worktree has no gaia ticket, so it is never on the work
-     * list and never touched — foreign-safety falls out of the DB-driven model
-     * with no host enumeration.
+     * scoped to THIS conductor (GAIA-121) — so it catches the orphans a
+     * live-tick-only path structurally cannot (the conductor was down when the
+     * ticket hit `done`, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * (non-gaia) worktree has no gaia ticket, so it is never on the work list; a
+     * ticket assigned to another conductor is filtered out at the query — both are
+     * left untouched with no host enumeration.
      *
      * Per ticket, close is DECOUPLED from teardown (no withholding): a done ticket
      * is closed at once as a lifecycle step, independent of whether its worktree
-     * teardown then succeeds. Teardown is best-effort + verified — `cleaned_up` is
-     * set only when the worktree was actually torn down ON THIS HOST. Since the
-     * query is not machine-scoped, a conductor may see a finished ticket whose
-     * worktree lives on ANOTHER host; `removeWorktree` returns `false` there (a
-     * clean "not here") and the reaper DEFERS — it does not flag the ticket
-     * cleaned, leaving the teardown to the host that physically holds the
-     * worktree. That gate is what keeps the not-machine-scoped query from
-     * cross-host-false-teardowning a still-live workspace. A teardown that throws
-     * logs loudly and leaves `cleaned_up=0`, so the next reconciliation retries;
-     * one miss never orphans the workspace (RC1). Re-running on an already-cleaned
-     * ticket is a no-op — it is off the list (idempotent). Each ticket is isolated
-     * in a try/catch so one failure never aborts the rest.
+     * teardown then succeeds. Because the list is conductor-scoped, every ticket's
+     * worktree belongs on THIS host: `removeWorktree` returning `false` means the
+     * directory was already deleted out of band (nothing left to remove), which is
+     * itself a completed teardown → flag `cleaned_up`. There is no cross-host defer
+     * (GAIA-121) — the manufactured ambiguity that required it is gone once the
+     * query no longer loads foreign tickets. A teardown that THROWS logs loudly and
+     * leaves `cleaned_up=0`, so the next reconciliation retries; one miss never
+     * orphans the workspace (RC1). Re-running on an already-cleaned ticket is a
+     * no-op — it is off the list (idempotent). Each ticket is isolated in a
+     * try/catch so one failure never aborts the rest.
      *
      * The `after_done` hook runs through the executor (GAIA-84), which owns the
      * best-effort policy — it logs+swallows a hook failure and never throws, so

package/dist/src/core/conductor.js

@@ -194,8 +194,22 @@ export class Conductor {
                 const log = r.worktreePath
                     ? await this.agent.getRunLog(r.worktreePath)
                     : '';
-                await this.remote.finalizeRun(r.runUuid, log);
-                this.logger.info({ run: r.runUuid }, 'run finalised');
+                // Footprint (GAIA-132): the agent parses its own transcript for the
+                // effort metrics (transcript format is agent-specific); the conductor
+                // adds duration_s from started_at → now. The conductor owns the run, so
+                // this write always lands (the agent session could not).
+                const parsed = this.agent.parseFootprint(log);
+                const now = Math.floor(Date.now() / 1000);
+                const metrics = {
+                    tokens: parsed.tokens,
+                    duration_s: r.startedAt !== undefined ? Math.max(0, now - r.startedAt) : 0,
+                    agent_turns: parsed.agent_turns,
+                    tool_calls: parsed.tool_calls,
+                    user_prompts: parsed.user_prompts,
+                    user_prompt_words: parsed.user_prompt_words,
+                };
+                await this.remote.finalizeRun(r.runUuid, log, metrics);
+                this.logger.info({ run: r.runUuid, footprint: metrics }, 'run finalised');
             }
             catch (err) {
                 this.logger.warn({ run: r.runUuid, err: String(err) }, 'run finalise failed');
@@ -208,34 +222,32 @@ export class Conductor {
      * flag via {@link GaiaRemote.fetchUncleanedTickets}: every ticket that is
      * finished (state=done OR closed) but not yet cleaned. The SAME reconciliation
      * runs on every tick AND standalone as `gaia conductor reap`, and the query is
-     * NOT machine-scoped — so it catches the orphans a live-tick-only path
-     * structurally cannot (RC2/RC3): the conductor was down when the ticket hit
-     * `done`, crashed mid-cleanup, or the ticket's `conductor_id` was reassigned.
-     * A foreign (non-gaia) worktree has no gaia ticket, so it is never on the work
-     * list and never touched — foreign-safety falls out of the DB-driven model
-     * with no host enumeration.
+     * scoped to THIS conductor (GAIA-121) — so it catches the orphans a
+     * live-tick-only path structurally cannot (the conductor was down when the
+     * ticket hit `done`, or crashed mid-cleanup) for its OWN tickets. A foreign
+     * (non-gaia) worktree has no gaia ticket, so it is never on the work list; a
+     * ticket assigned to another conductor is filtered out at the query — both are
+     * left untouched with no host enumeration.
      *
      * Per ticket, close is DECOUPLED from teardown (no withholding): a done ticket
      * is closed at once as a lifecycle step, independent of whether its worktree
-     * teardown then succeeds. Teardown is best-effort + verified — `cleaned_up` is
-     * set only when the worktree was actually torn down ON THIS HOST. Since the
-     * query is not machine-scoped, a conductor may see a finished ticket whose
-     * worktree lives on ANOTHER host; `removeWorktree` returns `false` there (a
-     * clean "not here") and the reaper DEFERS — it does not flag the ticket
-     * cleaned, leaving the teardown to the host that physically holds the
-     * worktree. That gate is what keeps the not-machine-scoped query from
-     * cross-host-false-teardowning a still-live workspace. A teardown that throws
-     * logs loudly and leaves `cleaned_up=0`, so the next reconciliation retries;
-     * one miss never orphans the workspace (RC1). Re-running on an already-cleaned
-     * ticket is a no-op — it is off the list (idempotent). Each ticket is isolated
-     * in a try/catch so one failure never aborts the rest.
+     * teardown then succeeds. Because the list is conductor-scoped, every ticket's
+     * worktree belongs on THIS host: `removeWorktree` returning `false` means the
+     * directory was already deleted out of band (nothing left to remove), which is
+     * itself a completed teardown → flag `cleaned_up`. There is no cross-host defer
+     * (GAIA-121) — the manufactured ambiguity that required it is gone once the
+     * query no longer loads foreign tickets. A teardown that THROWS logs loudly and
+     * leaves `cleaned_up=0`, so the next reconciliation retries; one miss never
+     * orphans the workspace (RC1). Re-running on an already-cleaned ticket is a
+     * no-op — it is off the list (idempotent). Each ticket is isolated in a
+     * try/catch so one failure never aborts the rest.
      *
      * The `after_done` hook runs through the executor (GAIA-84), which owns the
      * best-effort policy — it logs+swallows a hook failure and never throws, so
      * the core needs no per-call-site try/catch around it.
      */
     async reap() {
-        const tickets = await this.remote.fetchUncleanedTickets();
+        const tickets = await this.remote.fetchUncleanedTickets(this.id);
         for (const t of tickets) {
             try {
                 // Lifecycle: close a done+unclosed ticket at once, decoupled from the
@@ -259,9 +271,12 @@ export class Conductor {
                     });
                 }
                 if (this.executor.capabilities().persistent) {
-                    let removed;
                     try {
-                        removed = await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
+                        // The work list is scoped to this conductor (GAIA-121), so its
+                        // worktree belongs on THIS host. Whether removeWorktree tears one
+                        // down or finds it already gone (`false`), teardown is complete —
+                        // the boolean is irrelevant, only a THROW (a real failure) matters.
+                        await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
                     }
                     catch (err) {
                         this.logger.warn({
@@ -272,20 +287,6 @@ export class Conductor {
                         }, 'worktree teardown failed');
                         continue; // leave cleaned_up=0 → the next reconciliation retries.
                     }
-                    // A recorded worktree path that was NOT present on this host belongs
-                    // to another conductor's host (the query is not machine-scoped, so we
-                    // see every finished ticket). Do NOT flag it cleaned — that would be a
-                    // cross-host false-teardown, orphaning a still-live workspace. Defer:
-                    // the host that physically holds it reaps + flags it. A ticket with no
-                    // recorded path (nothing hosted to locate) falls through to cleaned.
-                    if (t.worktreePath && !removed) {
-                        this.logger.info({
-                            ticket: t.ticketUuid,
-                            branch: t.branchName,
-                            worktreePath: t.worktreePath,
-                        }, 'worktree not on this host — deferring teardown to its host');
-                        continue;
-                    }
                 }
                 // Teardown verified locally (or nothing hosted to tear down): flag it
                 // cleaned so it drops off the work list.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gaia-ai/conductor",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "GAIA conductor engine + CLI: registers, claims tickets via JSON:API, dispatches agents.",
   "type": "module",
   "license": "MIT",
@@ -25,10 +25,10 @@
     "directory": "conductor/packages/conductor"
   },
   "dependencies": {
-    "@gaia-ai/core": "^0.4.3",
+    "@gaia-ai/core": "^0.4.5",
     "@dropsh/plugin-oauth2": "^0.4.1",
-    "@dropsh/plugin-jsonapi-schema": "^0.5.1",
+    "@dropsh/plugin-jsonapi-schema": "^0.5.6",
     "commander": "^12.1.0",
-    "dropsh": "^0.5.3"
+    "dropsh": "^0.5.6"
   }
 }