@gaia-ai/conductor 0.4.6 → 0.5.0

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

@@ -1,12 +1,14 @@
-import { type ConductorFileConfig, type ConductorLogger, type GaiaAgent, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace } from '@gaia-ai/core';
+import { type ConductorFileConfig, type ConductorLogger, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace, type ResolvedAgent } from '@gaia-ai/core';
 import { Command } from 'commander';
 /** Test seam: inject any subset of dependencies. */
 export interface GaiaCliDeps {
     remote?: GaiaRemote;
     executor?: GaiaExecutor;
     workspace?: GaiaWorkspace;
-    agent?: GaiaAgent;
+    agents?: ResolvedAgent[];
     config?: ConductorFileConfig;
+    /** Injectable registry fetch for the start-time version check (tests). */
+    fetch?: typeof fetch;
 }
 export declare function parseHerdrJson(output: string, command: string): unknown;
 /**

package/dist/src/cli/gaia.js

@@ -1,15 +1,15 @@
-import { existsSync, readFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { existsSync } from 'node:fs';
+import { dirname } from 'node:path';
 import { createInterface } from 'node:readline';
-import { fileURLToPath } from 'node:url';
 import { CommandRunner, createLogger, exec, setDefaultCommandRunner, } from '@gaia-ai/core';
-import { selectAgent, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
+import { selectAgents, selectExecutor, selectRemote, selectWorkspace, } from '@gaia-ai/core/plugins';
 import { Command } from 'commander';
 import { authStatus, buildProgram as buildDropshProgram } from 'dropsh';
 import { loadConductorConfig, resolveConfigPath } from '../config.js';
 import { Conductor } from '../core/conductor.js';
 import { machineContextPath, readMachineContext, scaffold, } from './init.js';
 import * as registry from './local-registry.js';
+import { fetchUpdateNotice, printVersionLine, resolveCliVersion, runUpdate, } from './version-check.js';
 /**
  * Default config path. `--config` / `$GAIA_CONDUCTOR_CONFIG` win; otherwise walk
  * up from cwd to the nearest `.gaia/conductor.config.js` (git/eslint style), so a
@@ -185,8 +185,8 @@ async function cmdPoll(deps, log = {}) {
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
     const workspace = deps.workspace ?? (await selectWorkspace(config));
-    const agent = deps.agent ?? (await selectAgent(config));
-    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     await conductor.start();
     await conductor.tick();
 }
@@ -199,8 +199,8 @@ async function cmdReap(deps, log = {}) {
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
     const workspace = deps.workspace ?? (await selectWorkspace(config));
-    const agent = deps.agent ?? (await selectAgent(config));
-    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     // The reaper reconciles finished-but-uncleaned tickets (the cleaned_up flag)
     // against their worktrees; it needs no registration/heartbeat (it is not a
     // poll), just the executor + remote, so it runs standalone after a
@@ -216,8 +216,8 @@ async function cmdStartForeground(deps, log = {}) {
     const remote = await resolveRemote(deps, config);
     const executor = deps.executor ?? (await selectExecutor(config, logger));
     const workspace = deps.workspace ?? (await selectWorkspace(config));
-    const agent = deps.agent ?? (await selectAgent(config));
-    const conductor = new Conductor(config, remote, executor, workspace, agent, logger, checkoutRoot);
+    const agents = deps.agents ?? (await selectAgents(config));
+    const conductor = new Conductor(config, remote, executor, workspace, agents, logger, checkoutRoot);
     await conductor.start();
     const controller = new AbortController();
     const onSignal = () => controller.abort();
@@ -232,6 +232,24 @@ async function cmdStartForeground(deps, log = {}) {
     }
 }
 async function cmdStart(deps, log = {}) {
+    // Print the installed version (AC-2) immediately, then kick the newer-version
+    // registry check off CONCURRENTLY with config resolution so a slow/offline
+    // registry never stalls start (finding #1 — the check no longer runs serially
+    // before resolveConfig). Fail-silent + bounded (AC-3/AC-4/AC-5); the notice is
+    // printed once it resolves, after the start work below. Not in
+    // cmdStartForeground — that path is herdr-hosted, no TTY.
+    const current = printVersionLine();
+    const noticePromise = fetchUpdateNotice(current, deps.fetch ?? globalThis.fetch).catch(() => null);
+    try {
+        await cmdStartBody(deps, log);
+    }
+    finally {
+        const notice = await noticePromise;
+        if (notice !== null)
+            console.log(notice);
+    }
+}
+async function cmdStartBody(deps, log) {
     const config = await resolveConfig(deps);
     const checkoutRoot = checkoutRootOf(config);
     const logger = loggerFor(checkoutRoot, log);
@@ -373,25 +391,6 @@ async function promptSecret() {
     }
 }
 // --- program ----------------------------------------------------------------
-// Report the CLI's own package version. Walks up from this module to the
-// nearest @gaia-ai/conductor package.json so it resolves both from the
-// compiled dist/src/cli/gaia.js (3 dirs up) and the src/cli/gaia.ts vitest
-// runs (2 dirs up). Same release tag across packages ⇒ == @gaia-ai/gaia.
-function resolveCliVersion() {
-    let dir = dirname(fileURLToPath(import.meta.url));
-    for (let i = 0; i < 6; i++) {
-        try {
-            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
-            if (pkg.name === '@gaia-ai/conductor')
-                return pkg.version ?? '0.0.0';
-        }
-        catch {
-            // no package.json here — keep walking up
-        }
-        dir = dirname(dir);
-    }
-    return '0.0.0';
-}
 export function buildProgram(deps) {
     const program = new Command();
     program
@@ -417,6 +416,31 @@ export function buildProgram(deps) {
         .action(() => {
         console.log(cliVersion);
     });
+    program
+        .command('update')
+        .description('upgrade the globally installed gaia CLI to the latest npm release')
+        .action(async () => {
+        const { ok, before, after } = await runUpdate();
+        if (!ok) {
+            console.error('gaia update failed — see npm output above');
+            process.exitCode = 1;
+            return;
+        }
+        // Report the real on-disk change (finding #2): never a fabricated
+        // "latest", never a false "upgraded" when npm changed nothing.
+        if (after === null) {
+            console.log('gaia update completed (installed version undetermined)');
+        }
+        else if (before === null) {
+            console.log(`gaia installed: ${after}`);
+        }
+        else if (before === after) {
+            console.log(`gaia is already up to date (${after})`);
+        }
+        else {
+            console.log(`gaia updated: ${before} → ${after}`);
+        }
+    });
     const conductor = program
         .command('conductor')
         .description('node-agent lifecycle + local registry')

package/dist/src/cli/init.js

@@ -28,8 +28,10 @@ export function renderCommittedConfig(inputs) {
 // 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 — only the \`@gaia-ai/gaia/plugins\` host
-// barrel (many exports) still names one via \`export: 'drupalRemote'\`.
+// 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).
 
 // The user-global machine context: identity + connection (incl. secret), shared
 // by every project on this machine. Never committed.
@@ -79,8 +81,12 @@ export default {
     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'.
   workspace: {
-    plugin: '@gaia-ai/plugin-herdr-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

package/dist/src/cli/version-check.d.ts

@@ -0,0 +1,72 @@
+/** The global install target on npm (the meta package). */
+export declare const GAIA_PACKAGE = "@gaia-ai/gaia";
+/** The npm registry endpoint for the latest published version. */
+export declare const REGISTRY_LATEST_URL = "https://registry.npmjs.org/@gaia-ai/gaia/latest";
+/**
+ * The sentinel returned when the installed version cannot be resolved (the
+ * package.json walk failed). Never a real published release, so callers treat
+ * it as "unknown" and suppress the update notice rather than nagging.
+ */
+export declare const UNKNOWN_VERSION = "0.0.0";
+/**
+ * The currently installed CLI version. Walks up from this module to the nearest
+ * @gaia-ai/conductor package.json so it resolves both from the compiled
+ * dist/src/cli/version-check.js and from a vitest src run. Same release tag
+ * across packages ⇒ == @gaia-ai/gaia. Memoized — the version cannot change
+ * within a process, so the walk runs at most once (finding #6).
+ */
+export declare function resolveCliVersion(): string;
+/**
+ * Fetch the latest published version of @gaia-ai/gaia from the npm registry.
+ * Bounded by an AbortController timeout; NEVER throws — any failure (network,
+ * non-2xx, timeout, malformed JSON, missing field) resolves to null so the
+ * caller can treat the check as best-effort (AC-4). fetchImpl is injectable so
+ * tests run without network.
+ */
+export declare function fetchLatestVersion(fetchImpl?: typeof fetch, timeoutMs?: number): Promise<string | null>;
+/**
+ * A human-readable "update available" notice when `latest` is strictly newer
+ * than `current`, else null (already current or ahead — AC-5). Pure.
+ */
+export declare function updateNotice(current: string, latest: string): string | null;
+/** Spawns a command, inheriting stdio, resolving to its exit code. */
+export type SpawnUpdate = (cmd: string, args: string[]) => Promise<number>;
+/** Spawns a command, capturing stdout, resolving to its exit code + stdout. */
+export type SpawnCapture = (cmd: string, args: string[]) => Promise<{
+    code: number;
+    stdout: string;
+}>;
+/**
+ * Upgrade the globally installed gaia CLI to the latest published version via
+ * `npm install -g @gaia-ai/gaia@latest`. Reports the actual global version
+ * before and after the install (queried from npm, not from a separate registry
+ * fetch — finding #2), so the caller reports the real change: `before` is null
+ * when gaia was not installed globally, and no "upgraded" claim is made unless
+ * npm actually changed the on-disk version. On install failure `after` mirrors
+ * `before` and the post-install query is skipped. spawnImpl/captureImpl are
+ * injectable for tests.
+ */
+export declare function runUpdate(spawnImpl?: SpawnUpdate, captureImpl?: SpawnCapture): Promise<{
+    ok: boolean;
+    before: string | null;
+    after: string | null;
+}>;
+/**
+ * Print the installed gaia version line (AC-2), synchronously, and return it.
+ * Never blocks on the registry — the caller kicks off the newer-version check
+ * separately (see fetchUpdateNotice) so start is not stalled waiting on npm.
+ */
+export declare function printVersionLine(out?: (s: string) => void): string;
+/**
+ * Best-effort "update available" notice for the given installed version
+ * (AC-3/AC-5). Fetches the latest published version (fail-silent → null on any
+ * error, AC-4) and compares. Returns the notice string or null. fetchImpl is
+ * injectable for tests.
+ */
+export declare function fetchUpdateNotice(current: string, fetchImpl?: typeof fetch): Promise<string | null>;
+/**
+ * Print the installed gaia version (AC-2) and, best-effort, a newer-version
+ * notice (AC-3/AC-5). The registry check is fail-silent (AC-4): an offline
+ * registry prints only the version line. out/fetchImpl are injectable for tests.
+ */
+export declare function printStartVersionBanner(out?: (s: string) => void, fetchImpl?: typeof fetch): Promise<void>;

package/dist/src/cli/version-check.js

@@ -0,0 +1,182 @@
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import semver from 'semver';
+/** The global install target on npm (the meta package). */
+export const GAIA_PACKAGE = '@gaia-ai/gaia';
+/** The npm registry endpoint for the latest published version. */
+export const REGISTRY_LATEST_URL = 'https://registry.npmjs.org/@gaia-ai/gaia/latest';
+/**
+ * The sentinel returned when the installed version cannot be resolved (the
+ * package.json walk failed). Never a real published release, so callers treat
+ * it as "unknown" and suppress the update notice rather than nagging.
+ */
+export const UNKNOWN_VERSION = '0.0.0';
+let cachedCliVersion;
+/**
+ * The currently installed CLI version. Walks up from this module to the nearest
+ * @gaia-ai/conductor package.json so it resolves both from the compiled
+ * dist/src/cli/version-check.js and from a vitest src run. Same release tag
+ * across packages ⇒ == @gaia-ai/gaia. Memoized — the version cannot change
+ * within a process, so the walk runs at most once (finding #6).
+ */
+export function resolveCliVersion() {
+    if (cachedCliVersion !== undefined)
+        return cachedCliVersion;
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let i = 0; i < 6; i++) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+            if (pkg.name === '@gaia-ai/conductor') {
+                cachedCliVersion = pkg.version ?? UNKNOWN_VERSION;
+                return cachedCliVersion;
+            }
+        }
+        catch {
+            // no package.json here — keep walking up
+        }
+        dir = dirname(dir);
+    }
+    cachedCliVersion = UNKNOWN_VERSION;
+    return cachedCliVersion;
+}
+/**
+ * Fetch the latest published version of @gaia-ai/gaia from the npm registry.
+ * Bounded by an AbortController timeout; NEVER throws — any failure (network,
+ * non-2xx, timeout, malformed JSON, missing field) resolves to null so the
+ * caller can treat the check as best-effort (AC-4). fetchImpl is injectable so
+ * tests run without network.
+ */
+export async function fetchLatestVersion(fetchImpl = globalThis.fetch, timeoutMs = 1500) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(REGISTRY_LATEST_URL, {
+            signal: controller.signal,
+            headers: { accept: 'application/json' },
+        });
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        return typeof body.version === 'string' ? body.version : null;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * A human-readable "update available" notice when `latest` is strictly newer
+ * than `current`, else null (already current or ahead — AC-5). Pure.
+ */
+export function updateNotice(current, latest) {
+    // Unknown installed version ⇒ suppress the notice (finding #5): otherwise a
+    // failed package.json walk yields a perpetual bogus "0.0.0 → x.y.z" nag.
+    if (current === UNKNOWN_VERSION)
+        return null;
+    if (!semver.valid(current) || !semver.valid(latest))
+        return null;
+    if (!semver.gt(latest, current))
+        return null;
+    return (`A new gaia version is available: ${current} → ${latest}\n` +
+        'Run `gaia update` to upgrade.');
+}
+const defaultSpawn = (cmd, args) => new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: 'inherit', shell: false });
+    child.on('error', () => resolve(1));
+    child.on('close', (code) => resolve(code ?? 1));
+});
+const defaultCapture = (cmd, args) => new Promise((resolve) => {
+    let stdout = '';
+    const child = spawn(cmd, args, {
+        stdio: ['ignore', 'pipe', 'ignore'],
+        shell: false,
+    });
+    child.stdout?.on('data', (chunk) => {
+        stdout += String(chunk);
+    });
+    child.on('error', () => resolve({ code: 1, stdout }));
+    child.on('close', (code) => resolve({ code: code ?? 1, stdout }));
+});
+/**
+ * The version of the globally installed @gaia-ai/gaia, read from
+ * `npm ls -g @gaia-ai/gaia --json`, or null when it is not installed globally /
+ * the output cannot be parsed. This reflects what npm actually has on disk —
+ * independent of the (possibly dev-shim) CLI running this process.
+ */
+async function queryGlobalVersion(captureImpl) {
+    try {
+        const { stdout } = await captureImpl('npm', [
+            'ls',
+            '-g',
+            GAIA_PACKAGE,
+            '--json',
+            '--depth',
+            '0',
+        ]);
+        const parsed = JSON.parse(stdout);
+        const v = parsed.dependencies?.[GAIA_PACKAGE]?.version;
+        return typeof v === 'string' ? v : null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Upgrade the globally installed gaia CLI to the latest published version via
+ * `npm install -g @gaia-ai/gaia@latest`. Reports the actual global version
+ * before and after the install (queried from npm, not from a separate registry
+ * fetch — finding #2), so the caller reports the real change: `before` is null
+ * when gaia was not installed globally, and no "upgraded" claim is made unless
+ * npm actually changed the on-disk version. On install failure `after` mirrors
+ * `before` and the post-install query is skipped. spawnImpl/captureImpl are
+ * injectable for tests.
+ */
+export async function runUpdate(spawnImpl = defaultSpawn, captureImpl = defaultCapture) {
+    const before = await queryGlobalVersion(captureImpl);
+    const code = await spawnImpl('npm', [
+        'install',
+        '-g',
+        `${GAIA_PACKAGE}@latest`,
+    ]);
+    if (code !== 0)
+        return { ok: false, before, after: before };
+    const after = await queryGlobalVersion(captureImpl);
+    return { ok: true, before, after };
+}
+/**
+ * Print the installed gaia version line (AC-2), synchronously, and return it.
+ * Never blocks on the registry — the caller kicks off the newer-version check
+ * separately (see fetchUpdateNotice) so start is not stalled waiting on npm.
+ */
+export function printVersionLine(out = console.log) {
+    const current = resolveCliVersion();
+    out(`gaia v${current}`);
+    return current;
+}
+/**
+ * Best-effort "update available" notice for the given installed version
+ * (AC-3/AC-5). Fetches the latest published version (fail-silent → null on any
+ * error, AC-4) and compares. Returns the notice string or null. fetchImpl is
+ * injectable for tests.
+ */
+export async function fetchUpdateNotice(current, fetchImpl = globalThis.fetch) {
+    const latest = await fetchLatestVersion(fetchImpl);
+    if (latest === null)
+        return null;
+    return updateNotice(current, latest);
+}
+/**
+ * Print the installed gaia version (AC-2) and, best-effort, a newer-version
+ * notice (AC-3/AC-5). The registry check is fail-silent (AC-4): an offline
+ * registry prints only the version line. out/fetchImpl are injectable for tests.
+ */
+export async function printStartVersionBanner(out = console.log, fetchImpl = globalThis.fetch) {
+    const current = printVersionLine(out);
+    const notice = await fetchUpdateNotice(current, fetchImpl);
+    if (notice !== null)
+        out(notice);
+}

package/dist/src/config.d.ts

@@ -1,4 +1,4 @@
-import type { ConductorFileConfig } from '@gaia-ai/core';
+import type { AgentCandidate, 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
@@ -34,6 +34,15 @@ import type { ConductorFileConfig } from '@gaia-ai/core';
  * `triage` for unclassified tickets).
  */
 export declare const DEFAULT_AGENT_PROMPT: string;
+/**
+ * Resolve the `agent` slot into candidate(s), **preserving the authored shape**:
+ * a single descriptor/plugin/wrapper → a single `AgentCandidate`, an array →
+ * `AgentCandidate[]`. Each entry is either a bare descriptor/plugin or a
+ * `{ agent, priority? }` wrapper; the inner agent value is resolved through the
+ * same `agent` kind-guard as any slot, and a `priority` function is preserved
+ * verbatim (AC-1, AC-2). Normalization to a list happens at selection time.
+ */
+export declare function resolveAgents(raw: unknown, configPath: string): Promise<AgentCandidate | AgentCandidate[]>;
 /**
  * Resolve the conductor config path from `cwd`.
  *

package/dist/src/config.js

@@ -42,7 +42,7 @@ export const DEFAULT_AGENT_PROMPT = `You are a GAIA agent working ticket {identi
     `(gaia dropsh read gaia_ticket/gaia_ticket/$GAIA_ID --include comments), ` +
     `renders the intake splash, runs the {state} engine, and applies ` +
     `WORKFLOW.md's {state} policy. Do ONLY the {state} work — never start or ` +
-    `prepare a later state. When done, or if you are blocked, STOP and run /exit.`;
+    `prepare a later state.`;
 function requirePlugin(value, kind) {
     if (!isRecord(value) || value.kind !== kind) {
         throw new Error(`conductor config requires a ${kind} plugin in the "${kind}" slot`);
@@ -119,6 +119,31 @@ async function resolveSlot(value, kind, configPath) {
         : value;
     return requirePlugin(resolved, kind);
 }
+/**
+ * Resolve the `agent` slot into candidate(s), **preserving the authored shape**:
+ * a single descriptor/plugin/wrapper → a single `AgentCandidate`, an array →
+ * `AgentCandidate[]`. Each entry is either a bare descriptor/plugin or a
+ * `{ agent, priority? }` wrapper; the inner agent value is resolved through the
+ * same `agent` kind-guard as any slot, and a `priority` function is preserved
+ * verbatim (AC-1, AC-2). Normalization to a list happens at selection time.
+ */
+export async function resolveAgents(raw, configPath) {
+    const resolveOne = async (entry) => {
+        const hasWrapper = isRecord(entry) &&
+            'agent' in entry &&
+            !('kind' in entry) &&
+            !('plugin' in entry);
+        const agentValue = hasWrapper ? entry.agent : entry;
+        const priority = hasWrapper
+            ? entry.priority
+            : undefined;
+        const agent = await resolveSlot(agentValue, 'agent', configPath);
+        return { agent, ...(priority ? { priority } : {}) };
+    };
+    return Array.isArray(raw)
+        ? Promise.all(raw.map(resolveOne))
+        : resolveOne(raw);
+}
 /**
  * Resolve the `plugins[]` array: descriptor entries are constructed, already-
  * constructed entries pass through. No kind-guard (plugins are not slotted).
@@ -259,7 +284,7 @@ export async function loadConductorConfig(configFile) {
             : {}),
         remote: await resolveSlot(config.remote, 'remote', configPath),
         executor: await resolveSlot(config.executor, 'executor', configPath),
-        agent: await resolveSlot(config.agent, 'agent', configPath),
+        agent: await resolveAgents(config.agent, configPath),
         workspace: await resolveSlot(config.workspace, 'workspace', configPath),
         label,
         machine_id: machineId,

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

@@ -1,4 +1,4 @@
-import { type ConductorFileConfig, type ConductorLogger, type GaiaAgent, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace } from '@gaia-ai/core';
+import { type ConductorFileConfig, type ConductorLogger, type GaiaExecutor, type GaiaRemote, type GaiaWorkspace, type ResolvedAgent } from '@gaia-ai/core';
 /**
  * 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
@@ -14,11 +14,11 @@ export declare class Conductor {
     private readonly remote;
     private readonly executor;
     private readonly workspace;
-    private readonly agent;
+    private readonly agents;
     private readonly logger;
     private readonly checkoutRoot;
     private uuid;
-    constructor(config: ConductorFileConfig, remote: GaiaRemote, executor: GaiaExecutor, workspace: GaiaWorkspace, agent: GaiaAgent, logger: ConductorLogger, checkoutRoot?: string);
+    constructor(config: ConductorFileConfig, remote: GaiaRemote, executor: GaiaExecutor, workspace: GaiaWorkspace, agents: ResolvedAgent[], logger: ConductorLogger, checkoutRoot?: string);
     get id(): string;
     /** This conductor's registration payload, built from config. */
     private registration;
@@ -47,16 +47,17 @@ export declare class Conductor {
      *
      * 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. 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.
+     * teardown then succeeds. `cleaned_up` is flagged ONLY on a VERIFIED teardown
+     * (GAIA-141 RC-2): `removeWorktree` returns `true` when the worktree is gone on
+     * this host (removed by us, or confirmed already absent), `false` when it could
+     * not be resolved and may still be on disk (e.g. its `worktree_path` was never
+     * persisted). A `false` return — like a THROW — logs loudly and leaves
+     * `cleaned_up=0`, so the next reconciliation retries; flagging cleaned on an
+     * unverified teardown was the root cause of the ~28 never-touched leftovers,
+     * because the ticket then dropped off the (cleaned_up=0) work list forever.
+     * 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

@@ -1,4 +1,4 @@
-import { conductorId, } from '@gaia-ai/core';
+import { conductorId, selectAgent, } from '@gaia-ai/core';
 function sleep(ms, signal) {
     return new Promise((resolve) => {
         if (signal?.aborted) {
@@ -86,16 +86,16 @@ export class Conductor {
     remote;
     executor;
     workspace;
-    agent;
+    agents;
     logger;
     checkoutRoot;
     uuid = null;
-    constructor(config, remote, executor, workspace, agent, logger, checkoutRoot = process.cwd()) {
+    constructor(config, remote, executor, workspace, agents, logger, checkoutRoot = process.cwd()) {
         this.config = config;
         this.remote = remote;
         this.executor = executor;
         this.workspace = workspace;
-        this.agent = agent;
+        this.agents = agents;
         this.logger = logger;
         this.checkoutRoot = checkoutRoot;
     }
@@ -191,14 +191,21 @@ export class Conductor {
                         }
                     }
                 }
+                // Route to the agent that actually ran (GAIA-144): the persisted
+                // run.agent id, falling back to the first candidate for a run written
+                // before the field existed (empty id).
+                const resolved = this.agents.find((a) => a.id === r.agent) ?? this.agents[0];
+                if (!resolved) {
+                    throw new Error('no agent candidates configured for finalize');
+                }
                 const log = r.worktreePath
-                    ? await this.agent.getRunLog(r.worktreePath)
+                    ? await resolved.agent.getRunLog(r.worktreePath)
                     : '';
                 // 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 parsed = resolved.agent.parseFootprint(log);
                 const now = Math.floor(Date.now() / 1000);
                 const metrics = {
                     tokens: parsed.tokens,
@@ -231,16 +238,17 @@ export class Conductor {
      *
      * 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. 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.
+     * teardown then succeeds. `cleaned_up` is flagged ONLY on a VERIFIED teardown
+     * (GAIA-141 RC-2): `removeWorktree` returns `true` when the worktree is gone on
+     * this host (removed by us, or confirmed already absent), `false` when it could
+     * not be resolved and may still be on disk (e.g. its `worktree_path` was never
+     * persisted). A `false` return — like a THROW — logs loudly and leaves
+     * `cleaned_up=0`, so the next reconciliation retries; flagging cleaned on an
+     * unverified teardown was the root cause of the ~28 never-touched leftovers,
+     * because the ticket then dropped off the (cleaned_up=0) work list forever.
+     * 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
@@ -271,12 +279,14 @@ export class Conductor {
                     });
                 }
                 if (this.executor.capabilities().persistent) {
+                    let removed;
                     try {
-                        // 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);
+                        // removeWorktree returns whether the teardown was VERIFIED on this
+                        // host: `true` = the worktree is gone (removed by us, or confirmed
+                        // already absent); `false` = it could NOT be resolved and may still
+                        // be on disk (GAIA-141 RC-2 — e.g. worktree_path was never persisted
+                        // and herdr lost track of the branch). A THROW is a hard failure.
+                        removed = await this.executor.removeWorktree(t.branchName, t.worktreePath || undefined);
                     }
                     catch (err) {
                         this.logger.warn({
@@ -287,6 +297,19 @@ export class Conductor {
                         }, 'worktree teardown failed');
                         continue; // leave cleaned_up=0 → the next reconciliation retries.
                     }
+                    if (!removed) {
+                        // Unverified teardown (GAIA-141 RC-2): do NOT flag cleaned_up, or the
+                        // ticket drops off fetchUncleanedTickets (which filters cleaned_up=0)
+                        // and the orphan is never retried. Leave it on the work list so a
+                        // later reap — with a persisted path, or once the executor resolves
+                        // it via the parent-repo git worktree list — can finish the job.
+                        this.logger.warn({
+                            ticket: t.ticketUuid,
+                            branch: t.branchName,
+                            worktreePath: t.worktreePath,
+                        }, 'worktree teardown unverified — retrying next reap');
+                        continue; // leave cleaned_up=0 → the next reconciliation retries.
+                    }
                 }
                 // Teardown verified locally (or nothing hosted to tear down): flag it
                 // cleaned so it drops off the work list.
@@ -300,6 +323,11 @@ export class Conductor {
     }
     async dispatch(run) {
         const t = await this.remote.getTicket(run.ticketUuid);
+        // Config-side agent selection (GAIA-144): pick the highest-priority
+        // candidate for this ticket (labels/environments already sideloaded by
+        // getTicket, so priority(ticket) never fetches). The chosen id is persisted
+        // on the run below so the stateless finalize step routes footprint parsing.
+        const chosen = selectAgent(this.agents, t);
         const baseRef = t.baseBranch ? `origin/${t.baseBranch}` : undefined;
         // Resolve the run env once (per-ticket env_vars + core GAIA_* vars) and
         // inject it into BOTH the executor-owned lifecycle hooks AND the agent run
@@ -352,7 +380,7 @@ export class Conductor {
             run: { uuid: run.runUuid, id: run.runId, handler: run.handler },
             workspacePath: ws.path,
             instructions: ws.instructions,
-            command: this.agent.launchCommand(prompt),
+            command: chosen.agent.launchCommand(prompt),
             env,
         });
         this.logger.info({
@@ -365,7 +393,12 @@ export class Conductor {
         }, 'dispatched run');
         // The conductor — not the agent — knows the per-run git worktree path, so
         // it persists `worktree_path` to gaia_run here alongside the running state.
-        await this.remote.markRunning(run.runUuid, { worktree_path: ws.path });
+        // It also persists the chosen agent id (GAIA-144) for finalize footprint
+        // routing.
+        await this.remote.markRunning(run.runUuid, {
+            worktree_path: ws.path,
+            agent: chosen.id,
+        });
     }
     async serve(signal) {
         await this.pollLoop(signal);

package/package.json

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