@gaia-ai/core 0.5.4 → 0.6.0

package/dist/src/plugins/auth/basic.d.ts

@@ -6,6 +6,7 @@
  * hand-written into each dropsh.config.js.
  */
 export declare function basicAuthProvider(tokenBase64: string): {
+    kind: 'auth';
     id: string;
     authProvider: unknown;
 };

package/dist/src/plugins/auth/basic.js

@@ -31,5 +31,7 @@ export function basicAuthProvider(tokenBase64) {
             };
         },
     };
-    return { id: 'gaia-basic-auth', authProvider };
+    // GAIA-215: `.kind='auth'` makes the plugin tag total (every GAIA plugin
+    // self-identifies); dropsh ignores the extra field and reads `authProvider`.
+    return { kind: 'auth', id: 'gaia-basic-auth', authProvider };
 }

package/dist/src/plugins/builtins-preset.d.ts

@@ -0,0 +1,5 @@
+import type { GaiaPreset } from './preset.js';
+/** Conductor surface: the Drupal control-plane remote (the sole shipped remote). */
+export declare const remotes: GaiaPreset['remotes'];
+/** Connection surface: inline HTTP Basic auth, only when a `basic` token is set. */
+export declare const connectionPlugins: GaiaPreset['connectionPlugins'];

package/dist/src/plugins/builtins-preset.js

@@ -0,0 +1,32 @@
+// GAIA-215: the core built-ins preset, exposed as `@gaia-ai/core/builtins`. It
+// self-declares GAIA's shipped default contributions the way any addon does —
+// retiring the `@gaia-ai/core/plugins` barrel `export:` warts (`drupalRemote`,
+// `basicAuthProvider`). List it in `conductor.config.js` addons to auto-wire the
+// Drupal control-plane remote; list it in `gaia.config.js` addons with a
+// `{ basic: '<base64>' }` option for inline HTTP Basic auth. The barrel stays
+// for back-compat (the descriptor `export:` path); new configs name this preset.
+//
+// It deliberately does NOT contribute a workspace: every executor addon ships
+// its own paired workspace (herdr → herdrWorkspace, fake → fakeWorkspace), so a
+// builtin `gitWorkspace` would only fight the executor's workspace on the
+// canonical config (a guaranteed last-wins warning). A git-only setup can still
+// name `gitWorkspace` explicitly via the `@gaia-ai/core/plugins` barrel.
+//
+// It is deliberately light + dependency-free at the top level (factory calls
+// only), so the host can import it at boot without pulling the remote runtime.
+import { basicAuthProvider } from './auth/basic.js';
+import { drupalRemote } from './remote/drupal.js';
+/** Conductor surface: the Drupal control-plane remote (the sole shipped remote). */
+export const remotes = (acc) => [...acc, drupalRemote()];
+/** Connection surface: inline HTTP Basic auth, only when a `basic` token is set. */
+export const connectionPlugins = (acc, opts) => {
+    const o = (opts ?? {});
+    if (typeof o.basic !== 'string' || o.basic.trim() === '')
+        return acc;
+    // basicAuthProvider returns the dropsh auth-plugin shape ({ id, authProvider })
+    // minus `requiredModules` (dropsh tolerates its absence for auth-only plugins).
+    return [
+        ...acc,
+        basicAuthProvider(o.basic),
+    ];
+};

package/dist/src/plugins/discover-addons.d.ts

@@ -0,0 +1,22 @@
+import type { ConductorLogger } from '../core/logger.js';
+import type { AgentCandidate, ExecutorPlugin, RemotePlugin, WorkspacePlugin } from './plugins.js';
+import { type AddonEntry, type DiscoveredContributions, type GaiaSurface } from './preset.js';
+/**
+ * Discover + accumulate the `entries` for one `surface`. `bases` is the
+ * ESLint-style resolution order (config dir → cwd → install). Depth-first over
+ * meta-addon `addons` (children before parent), visited-set keyed by resolved
+ * path + serialized options (dedup + cycle-safe). Returns the accumulated
+ * per-extension-point arrays; singleton resolution is `resolveConductorSlots`.
+ */
+export declare function discoverAddons(entries: AddonEntry[] | undefined, surface: GaiaSurface, bases: string[], opts?: {
+    logger?: ConductorLogger;
+}): Promise<DiscoveredContributions>;
+/** The resolved conductor slots (last-wins singletons + agent candidate list). */
+export interface ResolvedConductorSlots {
+    remote?: RemotePlugin;
+    executor?: ExecutorPlugin;
+    workspace?: WorkspacePlugin;
+    agents: AgentCandidate[];
+}
+/** Resolve discovered conductor contributions into the four engine slots. */
+export declare function resolveConductorSlots(contributions: DiscoveredContributions, logger?: ConductorLogger): ResolvedConductorSlots;

package/dist/src/plugins/discover-addons.js

@@ -0,0 +1,228 @@
+// GAIA-215: addon discovery. One shared `discoverAddons(entries, surface, bases)`
+// called by the conductor loader, the connection loader, and the host — each
+// runs ONLY its surface's accumulators. Resolution reuses the ESLint-style
+// resolver (`resolveModuleEslintStyle`) so an addon named in a config resolves
+// the same way a slot plugin did before (config dir → cwd → install).
+//
+// Ordering / override semantics (Storybook never wrote these down; spec'd here):
+//   1. addons apply in `addons[]` ARRAY ORDER;
+//   2. a preset's `addons` children apply DEPTH-FIRST BEFORE the declaring preset
+//      (a parent overrides its children — essentials-style composition);
+//   3. the user config file is the final preset (its own `addons[]` are the
+//      top-level entries, processed last → it always wins);
+//   4. an EXACT duplicate addon (same resolved path AND same options) is
+//      processed once (visited-set keyed by path + serialized options) and
+//      warned — this also prevents meta-addon cycles and fixes the old one-level
+//      `composePlugins` flatten. The same package with DIFFERENT options is a
+//      legitimate multi-instance (e.g. two oauth2 profiles) and both load.
+// Per entry: resolve → import `<pkg>/preset` (fallback: the package's default
+// export adapted as a single contribution, logged) → run the surface's
+// accumulators with the entry's `with` → for `agents`, attach the entry's
+// `priority`. The runtime `.kind` guard is retained at singleton resolution.
+import { pathToFileURL } from 'node:url';
+import { resolveModuleEslintStyle } from '../cli/resolve-module.js';
+import { emptyContributions, PRESET_FUNCTION_KEYS, SURFACE_KEYS, } from './preset.js';
+function warnFrom(logger) {
+    if (logger)
+        return (msg) => logger.warn({}, msg);
+    return (msg) => {
+        console.warn(msg);
+    };
+}
+/** Normalize an `AddonEntry` to `{ spec, opts, priority }`. */
+function normalizeEntry(entry) {
+    if (typeof entry === 'string')
+        return { spec: entry, opts: undefined };
+    const spec = entry.use ?? entry.name;
+    if (typeof spec !== 'string' || spec.trim() === '') {
+        throw new Error(`addons[] entry must name a package via a string or { use } / { name }; got ${JSON.stringify(entry)}`);
+    }
+    return {
+        spec,
+        opts: entry.with ?? entry.options,
+        ...(entry.priority ? { priority: entry.priority } : {}),
+    };
+}
+/** Does an imported module look like a preset (any accumulator fn or `addons`)? */
+function isPresetShaped(mod) {
+    if (Array.isArray(mod.addons))
+        return true;
+    return PRESET_FUNCTION_KEYS.some((k) => typeof mod[k] === 'function');
+}
+/** Pick a module's single factory: the default export, else a sole function. */
+function pickFactory(mod) {
+    if (typeof mod.default === 'function') {
+        return mod.default;
+    }
+    const fns = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+    if (fns.length === 1)
+        return mod[fns[0]];
+    return undefined;
+}
+/**
+ * Adapt a not-yet-migrated package (no `./preset`, module not preset-shaped) by
+ * constructing its default/sole factory and routing the built plugin into the
+ * surface accumulator matching its `.kind`. Incremental-migration path; logged.
+ * A factory returning an array (dropsh `composePlugins` aggregator) is flattened.
+ */
+function adaptDefaultExport(mod, spec, warn) {
+    const factory = pickFactory(mod);
+    if (!factory) {
+        throw new Error(`addon '${spec}' has no ./preset, is not preset-shaped, and has no default/sole factory to adapt`);
+    }
+    warn(`addon '${spec}' has no ./preset export — adapting its default export (legacy; migrate it to a ./preset, GAIA-215 AC-3)`);
+    return {
+        connectionPlugins: (acc, opts) => {
+            const built = factory(opts);
+            const list = Array.isArray(built) ? built : [built];
+            // Route by kind: only plugins WITHOUT a GAIA engine kind are dropsh
+            // connection plugins; engine kinds are routed by the branches below.
+            const conn = list.filter((p) => !isEngineKind(p.kind));
+            return [
+                ...acc,
+                ...conn,
+            ];
+        },
+        remotes: (acc, opts) => routeByKind(factory, opts, 'remote', acc),
+        executors: (acc, opts) => routeByKind(factory, opts, 'executor', acc),
+        workspaces: (acc, opts) => routeByKind(factory, opts, 'workspace', acc),
+        agents: (acc, opts) => {
+            const built = factory(opts);
+            const list = Array.isArray(built) ? built : [built];
+            const agents = list.filter((p) => p.kind === 'agent');
+            return [...acc, ...agents.map((agent) => ({ agent }))];
+        },
+    };
+}
+function isEngineKind(kind) {
+    return (kind === 'remote' ||
+        kind === 'executor' ||
+        kind === 'workspace' ||
+        kind === 'agent');
+}
+function routeByKind(factory, opts, kind, acc) {
+    const built = factory(opts);
+    const list = Array.isArray(built) ? built : [built];
+    const matching = list.filter((p) => p.kind === kind);
+    return [...acc, ...matching];
+}
+/** Resolve + import the preset for one addon spec. Returns the preset + a stable
+ *  visited key (the resolved module path). */
+async function loadPreset(spec, bases, warn) {
+    // 1. the conventional `<pkg>/preset` subpath.
+    const presetPath = resolveModuleEslintStyle(`${spec}/preset`, bases);
+    if (presetPath !== undefined) {
+        const mod = (await import(pathToFileURL(presetPath).href));
+        if (!isPresetShaped(mod)) {
+            throw new Error(`addon '${spec}' exposes a ./preset that declares no contributions`);
+        }
+        return { preset: mod, key: presetPath };
+    }
+    // 2. the package's main export — either preset-shaped, or a legacy default.
+    const mainPath = resolveModuleEslintStyle(spec, bases);
+    if (mainPath === undefined) {
+        throw new Error(`addons[] cannot resolve addon '${spec}'`);
+    }
+    const mod = (await import(pathToFileURL(mainPath).href));
+    if (isPresetShaped(mod))
+        return { preset: mod, key: mainPath };
+    return { preset: adaptDefaultExport(mod, spec, warn), key: mainPath };
+}
+/** Run one preset's surface accumulators into `acc`, attaching `priority` to any
+ *  newly appended agent candidates. */
+async function applyPreset(preset, opts, priority, surface, acc) {
+    for (const key of SURFACE_KEYS[surface]) {
+        const fn = preset[key];
+        if (typeof fn !== 'function')
+            continue;
+        const before = key === 'agents' ? acc.agents.length : 0;
+        // biome-ignore lint/suspicious/noExplicitAny: heterogeneous per-key arrays
+        acc[key] = await fn(acc[key], opts);
+        if (key === 'agents' && priority) {
+            for (let i = before; i < acc.agents.length; i++) {
+                const c = acc.agents[i];
+                if (!c.priority)
+                    acc.agents[i] = { ...c, priority };
+            }
+        }
+    }
+}
+/**
+ * Discover + accumulate the `entries` for one `surface`. `bases` is the
+ * ESLint-style resolution order (config dir → cwd → install). Depth-first over
+ * meta-addon `addons` (children before parent), visited-set keyed by resolved
+ * path + serialized options (dedup + cycle-safe). Returns the accumulated
+ * per-extension-point arrays; singleton resolution is `resolveConductorSlots`.
+ */
+export async function discoverAddons(entries, surface, bases, opts = {}) {
+    const acc = emptyContributions();
+    if (!Array.isArray(entries) || entries.length === 0)
+        return acc;
+    const warn = warnFrom(opts.logger);
+    const visited = new Set();
+    const walk = async (list) => {
+        for (const entry of list) {
+            const { spec, opts: withOpts, priority } = normalizeEntry(entry);
+            const { preset, key } = await loadPreset(spec, bases, warn);
+            // Dedup on (resolved path + serialized options): an EXACT repeat is a
+            // mistake (skip + warn), but the SAME package with DIFFERENT `with` is a
+            // legitimate multi-instance (e.g. two @dropsh/plugin-oauth2 profiles —
+            // session + pm), so both must load. Cycle-safe: a meta-addon that re-lists
+            // itself with the same options hits the visited key and stops.
+            const dedupKey = `${key}${optionsKey(withOpts)}`;
+            if (visited.has(dedupKey)) {
+                warn(`addon '${spec}' already registered — skipping the exact duplicate`);
+                continue;
+            }
+            visited.add(dedupKey);
+            // Depth-first: meta-addon children apply BEFORE the declaring preset.
+            if (Array.isArray(preset.addons) && preset.addons.length > 0) {
+                await walk(preset.addons);
+            }
+            await applyPreset(preset, withOpts, priority, surface, acc);
+        }
+    };
+    await walk(entries);
+    return acc;
+}
+/** Stable-ish serialization of an addon entry's `with` options for dedup keying.
+ *  Functions collapse to a marker; unserializable values fall back to String(). */
+function optionsKey(opts) {
+    if (opts === undefined)
+        return '';
+    try {
+        return (JSON.stringify(opts, (_k, v) => (typeof v === 'function' ? '[fn]' : v)) ??
+            '');
+    }
+    catch {
+        return String(opts);
+    }
+}
+/** Take the LAST contributor for a singleton slot; warn when >1 competed; run
+ *  the runtime `.kind` guard so a mis-declared contribution still fails loudly. */
+function resolveSingleton(list, kind, logger) {
+    if (list.length === 0)
+        return undefined;
+    const warn = warnFrom(logger);
+    if (list.length > 1) {
+        const ids = list.map((p) => p.id ?? '<?>').join(', ');
+        warn(`${kind}: ${list.length} addons contributed a ${kind} ([${ids}]); using the last (override wins)`);
+    }
+    const picked = list[list.length - 1];
+    if (picked.kind !== kind) {
+        throw new Error(`addon contributed a '${picked.kind}' into the ${kind} slot`);
+    }
+    return picked;
+}
+/** Resolve discovered conductor contributions into the four engine slots. */
+export function resolveConductorSlots(contributions, logger) {
+    const remote = resolveSingleton(contributions.remotes, 'remote', logger);
+    const executor = resolveSingleton(contributions.executors, 'executor', logger);
+    const workspace = resolveSingleton(contributions.workspaces, 'workspace', logger);
+    return {
+        ...(remote ? { remote } : {}),
+        ...(executor ? { executor } : {}),
+        ...(workspace ? { workspace } : {}),
+        agents: contributions.agents,
+    };
+}

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

@@ -66,15 +66,20 @@ export interface GaiaExecutor {
      */
     stopRun(branch: string): Promise<void>;
     /**
-     * Tear down the run's hosted UI surface — for herdr, close every tab of the
-     * branch workspace via `herdr tab close <tab_id>` (killing the PTY). Called
-     * as the LAST finalisation step, strictly after the transcript is captured,
-     * and again at dispatch to clear a reused workspace's leftover tabs. Does NOT
-     * touch the branch worktree (that is the reap/{@link removeWorktree}
-     * lifecycle). Best-effort: one failing tab-close must not abort the others,
-     * finalisation, or dispatch. A no-op for non-persistent executors.
+     * Tear down ONE run's hosted UI surface — for herdr, close only the tab whose
+     * label carries the `#<runId>` token (`startRun` labels every tab
+     * `<identifier> · <state> #<run.id>`), via `herdr tab close <tab_id>` (killing
+     * that PTY). Run-scoped by design (GAIA-183): a sibling run's tab in the same
+     * branch workspace — a still-open prior-state run or a concurrent re-claim —
+     * and any non-run tab are left untouched. Called as the LAST finalisation step,
+     * strictly after the transcript is captured, and again at dispatch to clear a
+     * reused workspace's leftover tab for the run being (re-)started. No matching
+     * tab → a quiet no-op. Does NOT touch the branch worktree (that is the
+     * reap/{@link removeWorktree} lifecycle). Best-effort: a failing tab-close is
+     * swallowed and never aborts finalisation or dispatch. A no-op for
+     * non-persistent executors.
      */
-    cleanupRun(branch: string): Promise<void>;
+    cleanupRun(branch: string, runId: number): Promise<void>;
     /**
      * Tear down the branch's entire worktree (git worktree + hosted workspace),
      * reclaiming its disk. Called by the conductor's ticket-cleanup pass once a

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

@@ -0,0 +1,76 @@
+import type { DropSHPlugin } from 'dropsh/plugin';
+import type { AgentCandidate, ExecutorPlugin, RemotePlugin, WorkspacePlugin } from './plugins.js';
+import type { Ticket } from './remote/remote.js';
+/**
+ * A lazy command pointer (moved here from the host, GAIA-201, + `describe`). The
+ * command surface accumulates DESCRIPTORS — never constructed command plugins —
+ * so the host runs every addon's `commands` at boot without importing their
+ * runtime (preserves the GAIA-201 lazy-mount + "gaia --help imports none").
+ */
+export interface CommandDescriptor {
+    /** The subcommand name mounted as `gaia <name> …`. */
+    name: string;
+    /** Module specifier that default- (or `export`-) exports the `GaiaCommandPlugin`. */
+    plugin: string;
+    /** Shown in `gaia --help` even when the plugin is NOT loaded (describe-only stub). */
+    describe: string;
+    /** Named export to pick instead of the module default. */
+    export?: string;
+}
+/** The three surfaces, each named for its config home (surface = file = plugins). */
+export type GaiaSurface = 'command' | 'conductor' | 'connection';
+/**
+ * One entry in an `addons[]` array — a bare package name, or a descriptor naming
+ * the package (`use`, or SB's `name`) plus its `with` options and, for agents, a
+ * static `priority` over the ticket. Never carries a `kind`/`export`: the surface
+ * is decided by which preset function the addon exports; the kind by the
+ * contribution's own `.kind`.
+ */
+export type AddonEntry = string | {
+    /** The addon package (GAIA term). */
+    use?: string;
+    /** Storybook's term for the same field; accepted as an alias. */
+    name?: string;
+    /** Options handed to the addon's accumulators as `opts`. */
+    with?: unknown;
+    /** Alias for `with`. */
+    options?: unknown;
+    /** Agent-surface only: the static per-ticket priority (see `selectAgent`). */
+    priority?: (ticket: Ticket) => number;
+};
+/**
+ * The accumulated contributions across an `addons[]` list, one array per
+ * extension point. `discoverAddons` populates only the arrays belonging to the
+ * requested surface (the others stay empty) — so a connection load never runs
+ * the conductor accumulators.
+ */
+export interface DiscoveredContributions {
+    commands: CommandDescriptor[];
+    remotes: RemotePlugin[];
+    executors: ExecutorPlugin[];
+    workspaces: WorkspacePlugin[];
+    agents: AgentCandidate[];
+    connectionPlugins: DropSHPlugin[];
+}
+/** The extension points each surface runs (the preset function names to call). */
+export declare const SURFACE_KEYS: Record<GaiaSurface, Array<keyof DiscoveredContributions>>;
+/**
+ * A preset: named per-surface accumulator functions + a meta-addon `addons`
+ * array. Every accumulator is `(acc, opts) => acc` (sync or async); returning a
+ * new array lets an addon append, replace, or even FILTER a prior contribution
+ * (override semantics — the user config participates as the final preset).
+ */
+export interface GaiaPreset<O = unknown> {
+    /** Meta-addon composition: children apply depth-first BEFORE this preset. */
+    addons?: AddonEntry[];
+    commands?: (acc: CommandDescriptor[], opts: O) => CommandDescriptor[] | Promise<CommandDescriptor[]>;
+    remotes?: (acc: RemotePlugin[], opts: O) => RemotePlugin[] | Promise<RemotePlugin[]>;
+    executors?: (acc: ExecutorPlugin[], opts: O) => ExecutorPlugin[] | Promise<ExecutorPlugin[]>;
+    workspaces?: (acc: WorkspacePlugin[], opts: O) => WorkspacePlugin[] | Promise<WorkspacePlugin[]>;
+    agents?: (acc: AgentCandidate[], opts: O) => AgentCandidate[] | Promise<AgentCandidate[]>;
+    connectionPlugins?: (acc: DropSHPlugin[], opts: O) => DropSHPlugin[] | Promise<DropSHPlugin[]>;
+}
+/** The preset function keys, for shape-detection during discovery. */
+export declare const PRESET_FUNCTION_KEYS: Array<keyof DiscoveredContributions>;
+/** An empty contributions accumulator. */
+export declare function emptyContributions(): DiscoveredContributions;

package/dist/src/plugins/preset.js

@@ -0,0 +1,42 @@
+// GAIA-215: the preset contract — the Storybook-style self-declaration every
+// GAIA addon exposes through its `./preset` export subpath. A preset declares an
+// addon's contributions through named, per-surface ACCUMULATOR functions
+// `(acc, opts) => acc` (Storybook's `managerEntries`/`previewAnnotations` model),
+// plus an `addons` array for meta-addon composition. Each extension point is
+// list-valued; the core discovers presets and threads these accumulators, so a
+// conforming addon needs no per-slot `export:`/kind wiring in config.
+//
+// The three GAIA surfaces (each named for its config home):
+//   - command    → the `@gaia-ai/gaia` host registry (CommandDescriptor[]).
+//   - conductor  → the run engine (remote / executor / workspace / agent).
+//   - connection → dropsh (auth + renderer plugins).
+//
+// Settings (machine_id / project / states / hooks / scheduler) are NEVER
+// preset-contributed — identity must not be composable — so this interface has
+// no such members and an unknown preset export is rejected loudly at discovery.
+/** The extension points each surface runs (the preset function names to call). */
+export const SURFACE_KEYS = {
+    command: ['commands'],
+    conductor: ['remotes', 'executors', 'workspaces', 'agents'],
+    connection: ['connectionPlugins'],
+};
+/** The preset function keys, for shape-detection during discovery. */
+export const PRESET_FUNCTION_KEYS = [
+    'commands',
+    'remotes',
+    'executors',
+    'workspaces',
+    'agents',
+    'connectionPlugins',
+];
+/** An empty contributions accumulator. */
+export function emptyContributions() {
+    return {
+        commands: [],
+        remotes: [],
+        executors: [],
+        workspaces: [],
+        agents: [],
+        connectionPlugins: [],
+    };
+}

package/dist/src/plugins/remote/drupal.d.ts

@@ -30,6 +30,11 @@ export declare class DrupalGaiaRemote implements GaiaRemote {
      * ticket's run carries the path even after the run closed.
      */
     private latestRunWorktree;
+    resolveTicketByIdentifier(project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
+    private readonly projectUuidCache;
     private projectUuid;
 }
 export declare function drupalRemote(): RemotePlugin;

package/dist/src/plugins/remote/drupal.js

@@ -237,7 +237,7 @@ export class DrupalGaiaRemote {
             .where('conductor_id.machine_id', '=', id)
             .where('state', '=', 'done')
             .where('closed', '=', '0')
-            .fields(['worktree_path', 'agent'])
+            .fields(['worktree_path', 'agent', 'drupal_internal__id'])
             .page(100)
             .list();
         // No `started_at` read: the run's duration_s is derived from the agent
@@ -245,6 +245,8 @@ export class DrupalGaiaRemote {
         // the timestamp back through JSON:API.
         return rows.map((r) => ({
             runUuid: r.id,
+            // The `#<runId>` tab-label token: scopes the run's tab-close (GAIA-183).
+            runId: Number(r.attr('drupal_internal__id')),
             worktreePath: r.attr('worktree_path') ?? '',
             agent: r.attr('agent') ?? '',
         }));
@@ -331,7 +333,30 @@ export class DrupalGaiaRemote {
         }
         return '';
     }
+    async resolveTicketByIdentifier(project, identifier) {
+        // Scope by the project uuid: identifiers (GAIA-nnn) are unique per project,
+        // not globally, so a bare identifier filter could match another project's
+        // ticket in a multi-project instance.
+        const projectId = await this.projectUuid(project);
+        const t = await this.api
+            .collection('gaia_ticket')
+            .where('identifier', '=', identifier)
+            .where('project_id.id', '=', projectId)
+            .first();
+        if (!t) {
+            return null;
+        }
+        return { uuid: t.id, title: t.attr('title') ?? '' };
+    }
+    projectUuidCache = new Map();
     async projectUuid(name) {
+        // A project's name→uuid never changes, so cache it: gatherBatch resolves
+        // many identifiers per `gaia deployment tickets` call, each of which would
+        // otherwise re-fetch the same project.
+        const cached = this.projectUuidCache.get(name);
+        if (cached) {
+            return cached;
+        }
         const p = await this.api
             .collection('gaia_project')
             .where('name', '=', name)
@@ -339,6 +364,7 @@ export class DrupalGaiaRemote {
         if (!p) {
             throw new Error(`gaia project "${name}" not found`);
         }
+        this.projectUuidCache.set(name, p.id);
         return p.id;
     }
 }

package/dist/src/plugins/remote/fake.d.ts

@@ -102,6 +102,10 @@ export declare class FakeGaiaRemote implements GaiaRemote {
     fetchUncleanedTickets(conductorId: string): Promise<UncleanTicket[]>;
     closeTicket(uuid: string): Promise<void>;
     markTicketCleanedUp(uuid: string): Promise<void>;
+    resolveTicketByIdentifier(_project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
     /** Worktree path of the ticket's most recently seeded run, or '' when none. */
     private latestRunWorktree;
     private internalActiveRuns;

package/dist/src/plugins/remote/fake.js

@@ -168,6 +168,7 @@ export class FakeGaiaRemote {
             .filter((r) => r.state === 'done' && !r.closed)
             .map((r) => ({
             runUuid: r.runUuid,
+            runId: r.runId,
             worktreePath: r.worktreePath ?? '',
             agent: r.agent ?? '',
         }));
@@ -215,6 +216,10 @@ export class FakeGaiaRemote {
             t.cleanedUp = true;
         }
     }
+    async resolveTicketByIdentifier(_project, identifier) {
+        const hit = Object.entries(this.tickets).find(([, t]) => t.identifier === identifier);
+        return hit ? { uuid: hit[0], title: hit[1].title ?? '' } : null;
+    }
     /** Worktree path of the ticket's most recently seeded run, or '' when none. */
     latestRunWorktree(ticketUuid) {
         let worktree = '';

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

@@ -1,6 +1,7 @@
 export interface ConductorRegistration {
     id: string;
     project: string;
+    /** Empty = serve all claimable states in the project (GAIA-207). */
     states: string[];
     workspace: string;
     label: string;
@@ -62,6 +63,8 @@ export interface ConductorStatus {
 }
 export interface FinalizableRun {
     runUuid: string;
+    /** Numeric run id (the `#<runId>` tab-label token); scopes the run's tab-close at finalise (GAIA-183). */
+    runId: number;
     /** Absolute path of the per-run git worktree, or '' when unset. */
     worktreePath: string;
     /** Id of the agent that ran (GAIA-144); routes footprint parsing at finalize. '' / undefined when unset. */
@@ -188,4 +191,13 @@ export interface GaiaRemote {
      * already-cleaned ticket is a no-op (it is no longer on the list).
      */
     markTicketCleanedUp(uuid: string): Promise<void>;
+    /**
+     * Resolve a ticket identifier (e.g. "GAIA-134") to its uuid+title within a
+     * project, or null when no such ticket exists. Used by the
+     * `gaia deployment tickets` helper to turn commit-message identifiers into tickets.
+     */
+    resolveTicketByIdentifier(project: string, identifier: string): Promise<{
+        uuid: string;
+        title: string;
+    } | null>;
 }

package/dist/src/types.d.ts

@@ -13,7 +13,11 @@ export interface ConductorSettings {
     machine_id?: string;
     /** Project name (gaia_project.name); resolved at registration. */
     project: string;
-    /** Workflow states this conductor serves. */
+    /**
+     * Workflow states this conductor serves. An empty list means it serves every
+     * claimable state in its project; a non-empty list narrows it to those
+     * states (GAIA-207).
+     */
     states: string[];
     /**
      * Agent prompt template - the GAIA run contract, NOT project workflow. Bounds
@@ -50,3 +54,12 @@ export interface ConductorFileConfig extends ConductorSettings {
     /** dropsh-layer plugins (auth etc.); separate from the GAIA slots. */
     plugins?: DropSHPlugin[];
 }
+/**
+ * GAIA-201 split config model: the ENGINE half of a conductor config —
+ * everything a `conductor.config.js` carries EXCEPT the connection (`site`) and
+ * the auth `plugins`, which now live in a separate `gaia.config.js`
+ * (`GaiaConnectionConfig`). `loadConductorConfig` returns this; the conductor
+ * command composes it with the connection (`composeConductorConfig`) into the
+ * full `ConductorFileConfig` the engine consumes.
+ */
+export type ConductorEngineConfig = Omit<ConductorFileConfig, 'site' | 'plugins'>;