@gaia-ai/conductor 0.6.0 → 0.6.1

package/dist/src/config.js

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

package/dist/src/contract.d.ts

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

package/dist/src/contract.js

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

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

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

package/dist/src/core/conductor.js

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

package/dist/src/index.d.ts

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

package/dist/src/index.js

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

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

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

package/dist/src/plugins/agent.js

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

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

@@ -0,0 +1,104 @@
+export interface SpawnedSession {
+    sessionRef: string;
+}
+export interface ExecutorCapabilities {
+    persistent: boolean;
+}
+export interface SpawnRunInput {
+    ticket: {
+        uuid: string;
+        identifier: string;
+        title: string;
+        branchName: string;
+        state: string;
+        url?: string;
+    };
+    run: {
+        uuid: string;
+        id: number;
+        handler: string;
+    };
+    workspacePath: string;
+    instructions: {
+        path: string;
+        sha256: string;
+        text: string;
+    } | null;
+    command?: string;
+    env?: Record<string, string>;
+}
+/** The four lifecycle-hook slots, keyed exactly like `config.hooks`. */
+export type HookName = 'after_create' | 'before_run' | 'after_run' | 'after_done';
+/** Context for a hook invocation — carries the ticket for observable logging. */
+export interface HookContext {
+    /** The ticket identifier/uuid the hook is running for (log context). */
+    ticket: string;
+}
+export interface GaiaExecutor {
+    id: string;
+    capabilities(): ExecutorCapabilities;
+    /**
+     * Run the lifecycle hook `name` (command from `config.hooks[name]`) in `cwd`,
+     * best-effort. This is the SINGLE catch point for all lifecycle hooks:
+     *
+     * - MUST NEVER throw. No configured command → silent no-op. A failing command
+     *   → `logger.error({hook,worktree,ticket,err}, 'lifecycle hook failed')` then
+     *   return. So a hook failure never aborts dispatch or wedges a run in
+     *   `claimed`.
+     * - The underlying shell command still fails honestly (a non-zero exit
+     *   rejects); only the executor catches + logs + continues.
+     *
+     * `env`, when given, is the run's resolved environment (per-ticket env_vars
+     * merged with the core GAIA_* vars, GAIA-99), merged over the hook process's
+     * inherited env. Values may be sensitive — implementations must never log
+     * them (log key names only).
+     */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<void>;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    /**
+     * Signal the run's agent to stop. Called by the conductor's run-finalise pass
+     * BEFORE it captures the agent transcript (GAIA-132), so a stop must not
+     * destroy the log. For herdr this is a NO-OP: at finalise time the agent is
+     * idle and its jsonl transcript is already fully written to disk, and the
+     * subsequent {@link cleanupRun} tab-close kills the PTY (the agent dies with
+     * it). The seam exists for executors whose agent outlives its UI surface.
+     * Best-effort; gated by the conductor on `capabilities().persistent`.
+     */
+    stopRun(branch: string): Promise<void>;
+    /**
+     * 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, 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
+     * ticket is done. A no-op for non-persistent executors (no hosted workspace);
+     * the conductor gates the call on `capabilities().persistent`.
+     *
+     * `worktreePath` is the stable, identifier-derived worktree path (from the
+     * ticket's latest run). Prefer it over `branch` to resolve the worktree: the
+     * checked-out branch is mutable (the coding agent may rename/switch it), the
+     * path is not.
+     *
+     * Returns whether the worktree was actually present on THIS host and torn
+     * down (or reclaimed on disk) — i.e. whether the teardown happened locally.
+     * `false` means nothing matched here: the worktree is either already gone or
+     * lives on another conductor's host. The reaper uses this to avoid marking a
+     * ticket `cleaned_up` for a worktree it did not actually tear down (a
+     * cross-host false-teardown), leaving it for the host that physically holds
+     * it. A genuine failure still throws (surfaced as a teardown miss); a `false`
+     * return is a clean "not here", not an error.
+     */
+    removeWorktree(branch: string, worktreePath?: string): Promise<boolean>;
+}

package/dist/src/plugins/executor.js

@@ -0,0 +1 @@
+export {};