@gaia-ai/conductor 0.4.0

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

@@ -0,0 +1,82 @@
+export interface InitInputs {
+    baseUrl: string;
+    project: string;
+    clientId: string;
+    /** The resolved OAuth client secret value (stored in the machine context). */
+    secret: string;
+    machineId?: string;
+    userId?: string;
+}
+export interface ScaffoldOptions {
+    configPath: string;
+    force: boolean;
+    machinePath?: string;
+    /** When true, scaffold the committed config only — never read/write the machine context. */
+    skipMachine?: boolean;
+    /** When true, scaffold the machine context only — never write the committed config. */
+    skipCommitted?: boolean;
+}
+export interface ScaffoldResult {
+    committedPath: string;
+    wroteCommitted: boolean;
+    machine: MachineContextResult;
+}
+/**
+ * The user-global machine context: a plain importable module carrying the
+ * developer's machine identity and connection (incl. the OAuth client secret).
+ * Committed configs import it to compose machine_id and read
+ * base_url / client_id / client_secret. Gitignored, user-only (chmod 0600).
+ */
+export interface MachineContext {
+    machine_id: string;
+    user_id: string;
+    base_url: string;
+    client_id: string;
+    client_secret: string;
+}
+export interface MachineContextOptions {
+    path: string;
+    userId: string;
+    baseUrl: string;
+    clientId: string;
+    secret: string;
+    machineId?: string;
+}
+export interface MachineContextResult {
+    path: string;
+    created: boolean;
+    filledKeys: string[];
+}
+/**
+ * The committed, structural conductor config. `project` is the only per-repo
+ * value and is baked in here; connection + identity (incl. the secret) come from
+ * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
+ * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
+ * optional, gitignored conductor.config.local.js beside this file may override
+ * any field — it is loaded if present but never created by `gaia conductor init`.
+ */
+export declare function renderCommittedConfig(inputs: Pick<InitInputs, 'project'>): string;
+/** The user-global machine context module: identity + connection (incl. secret). */
+export declare function renderMachineContext(ctx: MachineContext): string;
+/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
+export declare function machineContextPath(): string;
+/** Import an existing context module's default export, or {} if absent/broken. */
+export declare function readMachineContext(path: string): Promise<Partial<MachineContext>>;
+/**
+ * Create-if-missing / fill-only-missing the user-global machine context.
+ * Existing values always win; only absent/blank keys are filled. machine_id
+ * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
+ * The file is written user-only (chmod 0600) since it holds the client secret.
+ */
+export declare function scaffoldMachineContext(opts: MachineContextOptions): Promise<MachineContextResult>;
+/**
+ * Scaffold the two conductor config files: the committed conductor.config.js
+ * (created only if missing — never overwritten unless `force`) and the
+ * user-global machine context (create-if-missing / fill-only-missing). The
+ * optional per-project conductor.config.local.js is NOT generated.
+ *
+ * `skipMachine` writes the committed config only (project-only setup); its
+ * mirror `skipCommitted` writes the machine context only (machine-only
+ * onboarding, no repo). Setting both is a no-op.
+ */
+export declare function scaffold(inputs: InitInputs, opts: ScaffoldOptions): Promise<ScaffoldResult>;

package/dist/src/cli/init.js

@@ -0,0 +1,232 @@
+import { chmodSync, existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+/** JS single-quoted string literal for a trusted, simple value. */
+function q(value) {
+    return `'${value.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+}
+/**
+ * The committed, structural conductor config. `project` is the only per-repo
+ * value and is baked in here; connection + identity (incl. the secret) come from
+ * the user-global machine context (~/.config/conductor/conductor.config.machine.js),
+ * and machine_id is composed as `${user_id}-${machine_id}-${project}`. An
+ * optional, gitignored conductor.config.local.js beside this file may override
+ * any field — it is loaded if present but never created by `gaia conductor init`.
+ */
+export function renderCommittedConfig(inputs) {
+    return `// Canonical GAIA conductor config — committed. Connection + identity come from
+// your user-global machine context (~/.config/conductor/conductor.config.machine.js:
+// { machine_id, user_id, base_url, client_id, client_secret }); machine_id is
+// composed here as \`\${user_id}-\${machine_id}-\${project}\`. \`project\` is the only
+// per-repo value and is baked in below. The client_secret is read from the
+// machine context (gitignored, user-only) — never committed here.
+//
+// IMPORT-FREE (GAIA-78): the plugin slots + plugins[] are \`{ plugin, with }\`
+// descriptors naming the REAL published package (\`@gaia-ai/plugin-*\`,
+// \`@dropsh/plugin-*\`), not \`import\`ed constructors. loadConductorConfig
+// 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'\`.
+
+// The user-global machine context: identity + connection (incl. secret), shared
+// by every project on this machine. Never committed.
+async function loadMachine() {
+  try {
+    return (await import(\`\${process.env.HOME}/.config/conductor/conductor.config.machine.js\`)).default ?? {};
+  } catch {}
+  return {};
+}
+
+// OPTIONAL per-project override — create conductor.config.local.js beside this
+// file to override any field (machine_id, base_url, model, …). It is loaded only
+// if present and is NOT created by \`gaia conductor init\`.
+async function loadLocal() {
+  try { return (await import('./conductor.config.local.js')).default ?? {}; } catch {}
+  return {};
+}
+
+const machine = await loadMachine();
+const local = await loadLocal();
+const project = local.project ?? ${q(inputs.project)};
+const baseUrl = local.base_url ?? machine.base_url;
+const clientId = local.oauth?.client_id ?? machine.client_id ?? 'gaia-agent';
+const clientSecret = local.oauth?.client_secret ?? machine.client_secret;
+const composedMachineId =
+  machine.user_id && machine.machine_id
+    ? \`\${machine.user_id}-\${machine.machine_id}-\${project}\`
+    : undefined;
+
+export default {
+  site: { base_url: baseUrl, jsonapi_prefix: local.jsonapi_prefix ?? '/jsonapi' },
+  project,
+  machine_id: local.machine_id ?? composedMachineId,
+  states: ['spec', 'diagnose', 'coding', 'review'],
+  max_parallel: 5,
+  // Lifecycle hooks are executor-owned (GAIA-84): the executor invokes each
+  // best-effort (logs loudly + continues, never aborts a run), so they live at
+  // the config top level — NOT on a plugin descriptor's \`with.hooks\`.
+  hooks: { after_create: 'ddev init-worktree', after_done: 'ddev delete -Oy' },
+  remote: { plugin: '@gaia-ai/gaia/plugins', export: 'drupalRemote' },
+  // No hard-wired diff pane for review: the review diff surface is hunk
+  // (GAIA-55) — agent-driven + opt-in in the human's interactive pane, not an
+  // executor-forced git-diff pane. Clicking a changed file in that hunk pane
+  // opens it editable in a spiceedit overlay (see conductor/README.md).
+  executor: { plugin: '@gaia-ai/plugin-herdr' },
+  agent: {
+    plugin: '@gaia-ai/plugin-claude',
+    with: { model: local.model ?? 'claude-opus-4-8' },
+  },
+  workspace: {
+    plugin: '@gaia-ai/plugin-herdr-workspace',
+  },
+  // 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
+  // resolver (\`export ?? 'default'\`, no sole-function auto-pick) on every
+  // \`gaia dropsh …\` command. @dropsh/plugin-oauth2 has no default export, so
+  // these entries MUST name \`export: 'oauth2Plugin'\` — unlike the four conductor
+  // slots above, which the conductor resolves and auto-picks.
+  plugins: [
+    {
+      plugin: '@dropsh/plugin-oauth2',
+      export: 'oauth2Plugin',
+      with: {
+        id: 'session',
+        default: true,
+        type: 'oauth2_client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+        token_url: \`\${baseUrl}/oauth/token\`,
+        scope: 'gaia:session',
+      },
+    },
+    {
+      plugin: '@dropsh/plugin-oauth2',
+      export: 'oauth2Plugin',
+      with: {
+        id: 'pm',
+        type: 'oauth2_client_credentials',
+        client_id: clientId,
+        client_secret: clientSecret,
+        token_url: \`\${baseUrl}/oauth/token\`,
+        scope: 'gaia:project_manager',
+      },
+    },
+  ],
+};
+`;
+}
+/** The user-global machine context module: identity + connection (incl. secret). */
+export function renderMachineContext(ctx) {
+    return `// User-global conductor context — gitignored, user-only (chmod 0600), never
+// committed. A plain importable module holding your machine identity +
+// connection, incl. the OAuth client secret. Committed conductor.config.js files
+// import this to compose machine_id (\`\${user_id}-\${machine_id}-\${project}\`) and
+// read base_url / client_id / client_secret. Created and gap-filled by
+// \`gaia conductor init\`; existing values are never overwritten.
+export default {
+  machine_id: ${q(ctx.machine_id)},
+  user_id: ${q(ctx.user_id)},
+  base_url: ${q(ctx.base_url)},
+  client_id: ${q(ctx.client_id)},
+  client_secret: ${q(ctx.client_secret)},
+};
+`;
+}
+/** The user-global machine context path: ~/.config/conductor/conductor.config.machine.js */
+export function machineContextPath() {
+    return join(process.env.HOME ?? '', '.config', 'conductor', 'conductor.config.machine.js');
+}
+/** Import an existing context module's default export, or {} if absent/broken. */
+export async function readMachineContext(path) {
+    if (!existsSync(path))
+        return {};
+    try {
+        // Cache-bust so a re-render within one process re-reads fresh.
+        const mod = await import(`${pathToFileURL(path).href}?t=${Date.now()}`);
+        const raw = mod.default;
+        return raw && typeof raw === 'object'
+            ? raw
+            : {};
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * Create-if-missing / fill-only-missing the user-global machine context.
+ * Existing values always win; only absent/blank keys are filled. machine_id
+ * defaults to hostname(). A no-op (no rewrite) when the file is already complete.
+ * The file is written user-only (chmod 0600) since it holds the client secret.
+ */
+export async function scaffoldMachineContext(opts) {
+    const existing = await readMachineContext(opts.path);
+    const derived = {
+        machine_id: opts.machineId ?? hostname(),
+        user_id: opts.userId,
+        base_url: opts.baseUrl,
+        client_id: opts.clientId,
+        client_secret: opts.secret,
+    };
+    const filledKeys = [];
+    const merged = { ...derived, ...existing };
+    for (const key of [
+        'machine_id',
+        'user_id',
+        'base_url',
+        'client_id',
+        'client_secret',
+    ]) {
+        const cur = existing[key];
+        if (typeof cur !== 'string' || cur.trim() === '') {
+            merged[key] = derived[key];
+            filledKeys.push(key);
+        }
+    }
+    const created = !existsSync(opts.path);
+    if (filledKeys.length > 0 || created) {
+        mkdirSync(dirname(opts.path), { recursive: true });
+        writeFileSync(opts.path, renderMachineContext(merged), 'utf8');
+    }
+    // Always tighten perms — the file holds a secret.
+    if (existsSync(opts.path))
+        chmodSync(opts.path, 0o600);
+    return { path: opts.path, created, filledKeys };
+}
+/**
+ * Scaffold the two conductor config files: the committed conductor.config.js
+ * (created only if missing — never overwritten unless `force`) and the
+ * user-global machine context (create-if-missing / fill-only-missing). The
+ * optional per-project conductor.config.local.js is NOT generated.
+ *
+ * `skipMachine` writes the committed config only (project-only setup); its
+ * mirror `skipCommitted` writes the machine context only (machine-only
+ * onboarding, no repo). Setting both is a no-op.
+ */
+export async function scaffold(inputs, opts) {
+    const committedPath = opts.configPath;
+    let wroteCommitted = false;
+    if (!opts.skipCommitted) {
+        mkdirSync(dirname(committedPath), { recursive: true });
+        if (!existsSync(committedPath) || opts.force) {
+            writeFileSync(committedPath, renderCommittedConfig(inputs), 'utf8');
+            wroteCommitted = true;
+        }
+    }
+    const machinePath = opts.machinePath ?? machineContextPath();
+    const machine = opts.skipMachine
+        ? { path: machinePath, created: false, filledKeys: [] }
+        : await scaffoldMachineContext({
+            path: machinePath,
+            userId: inputs.userId ?? '',
+            baseUrl: inputs.baseUrl,
+            clientId: inputs.clientId,
+            secret: inputs.secret,
+            ...(inputs.machineId !== undefined
+                ? { machineId: inputs.machineId }
+                : {}),
+        });
+    return { committedPath, wroteCommitted, machine };
+}

package/dist/src/cli/local-registry.d.ts

@@ -0,0 +1,14 @@
+export interface ConductorRegistryEntry {
+    id: string;
+    path: string;
+    project: string;
+    label: string;
+    host: 'herdr' | 'process' | 'systemd';
+    handle: string;
+}
+/** `${GAIA_HOME ?? ~}/.gaia/conductors.json`. */
+export declare function registryPath(): string;
+export declare function register(entry: ConductorRegistryEntry): Promise<void>;
+export declare function remove(id: string): Promise<void>;
+export declare function list(): Promise<ConductorRegistryEntry[]>;
+export declare function get(id: string): Promise<ConductorRegistryEntry | null>;

package/dist/src/cli/local-registry.js

@@ -0,0 +1,56 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+/** `${GAIA_HOME ?? ~}/.gaia/conductors.json`. */
+export function registryPath() {
+    const home = process.env.GAIA_HOME ?? homedir();
+    return join(home, '.gaia', 'conductors.json');
+}
+async function read() {
+    let raw;
+    try {
+        raw = await readFile(registryPath(), 'utf8');
+    }
+    catch {
+        return {};
+    }
+    if (raw.trim() === '') {
+        return {};
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === 'object' &&
+            parsed !== null &&
+            !Array.isArray(parsed)) {
+            return parsed;
+        }
+        return {};
+    }
+    catch {
+        return {};
+    }
+}
+async function write(data) {
+    const path = registryPath();
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+export async function register(entry) {
+    const data = await read();
+    data[entry.id] = entry;
+    await write(data);
+}
+export async function remove(id) {
+    const data = await read();
+    if (data[id]) {
+        delete data[id];
+        await write(data);
+    }
+}
+export async function list() {
+    return Object.values(await read());
+}
+export async function get(id) {
+    const data = await read();
+    return data[id] ?? null;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,23 @@
+import { type ConductorFileConfig } from '@gaia-ai/core';
+/**
+ * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
+ * the agent must stop instead of running the whole flow in one session. The run
+ * is closed automatically when the ticket state changes on the next claim - the
+ * agent does not release it. Run mechanics live here (not in the repo's
+ * WORKFLOW.md). A conductor config may override via the `prompt` field.
+ * Placeholders: `{identifier}`, `{state}`, `{runUuid}`, `{comments}` ({state}
+ * falls back to `triage` for unclassified tickets; {comments} is the ticket's
+ * comments, oldest first, or a "no comments yet" note).
+ */
+export declare const DEFAULT_AGENT_PROMPT: string;
+/**
+ * Resolve the conductor config path from `cwd`. An explicit `--config`
+ * override or `$GAIA_CONDUCTOR_CONFIG` wins verbatim (short-circuit, no
+ * filesystem walk). Otherwise walk from `cwd` root-ward (git/eslint style) to
+ * the nearest ancestor holding `.gaia/conductor.config.js` and return that
+ * absolute path — so any subdirectory of a project/worktree resolves the same
+ * config. If none is found up to the filesystem root, throw a clear, actionable
+ * error instead of leaking a raw "Cannot find module" from a later import().
+ */
+export declare function resolveConfigPath(override?: string, cwd?: string): string;
+export declare function loadConductorConfig(configFile: string): Promise<ConductorFileConfig>;

package/dist/src/config.js

@@ -0,0 +1,217 @@
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { conductorId, } from '@gaia-ai/core';
+/**
+ * Default agent prompt - the GAIA run contract. One run works EXACTLY one state;
+ * the agent must stop instead of running the whole flow in one session. The run
+ * is closed automatically when the ticket state changes on the next claim - the
+ * agent does not release it. Run mechanics live here (not in the repo's
+ * WORKFLOW.md). A conductor config may override via the `prompt` field.
+ * Placeholders: `{identifier}`, `{state}`, `{runUuid}`, `{comments}` ({state}
+ * falls back to `triage` for unclassified tickets; {comments} is the ticket's
+ * comments, oldest first, or a "no comments yet" note).
+ */
+export const DEFAULT_AGENT_PROMPT = `You are a GAIA agent working ticket {identifier}, current state: {state}. ` +
+    `Follow the "{state}" section of ./WORKFLOW.md in this repository. ` +
+    `This run covers EXACTLY the {state} state - do only its work. Do not start, ` +
+    `prepare, or perform any later state's work, even if WORKFLOW.md mentions ` +
+    `transitioning onward. When the {state} work is done and you have no open ` +
+    `questions, STOP - do not pick up or work any further state or ticket. If ` +
+    `blocked or you need a human, stop and surface the blocker. After you have ` +
+    `written the ticket's next state, run /exit to end this session.\n\n` +
+    `The ticket's comments are included below (oldest first). Read them before ` +
+    `acting: the latest \`summary\` is the review feedback you MUST address, and ` +
+    `any \`spec\`/\`debug_diagnose\` is the agreed plan/diagnosis. Treat their ` +
+    `points as in-scope acceptance criteria.\n\n--- Ticket comments ---\n{comments}`;
+function requirePlugin(value, kind) {
+    if (!isRecord(value) || value.kind !== kind) {
+        throw new Error(`conductor config requires a ${kind} plugin in the "${kind}" slot`);
+    }
+    return value;
+}
+/**
+ * A named-plugin descriptor `{ plugin, export?, with?/options? }` — the
+ * import-free form. `config.ts` resolves it into a constructed plugin, so a
+ * committed conductor.config.js need not `import` its plugin packages (which
+ * would resolve relative to the config file, not the CLI — the source of the
+ * "unknown command dropsh" breakage after the @gaia → @gaia-ai scope rename).
+ * Mirror of dropsh 0.4.1 `loadNamedPlugin` / `resolveSlot`.
+ */
+function isPluginDescriptor(entry) {
+    return isRecord(entry) && typeof entry.plugin === 'string';
+}
+/**
+ * Resolve + construct a descriptor. Resolution base order, ESLint-style:
+ * config dir → cwd → conductor install (`import.meta.url`) — the first
+ * `createRequire(base).resolve(name)` that succeeds wins. Then `import` the
+ * module, pick `export` (default 'default'), and call the factory with
+ * `with` (falling back to `options`).
+ */
+async function loadNamedPlugin(entry, configPath) {
+    const bases = [
+        pathToFileURL(configPath).href,
+        pathToFileURL(`${process.cwd()}/`).href,
+        import.meta.url,
+    ];
+    let resolved;
+    for (const base of bases) {
+        try {
+            resolved = createRequire(base).resolve(entry.plugin);
+            break;
+        }
+        catch {
+            // try the next base
+        }
+    }
+    if (resolved === undefined) {
+        throw new Error(`conductor config cannot resolve plugin '${entry.plugin}'`);
+    }
+    const mod = (await import(pathToFileURL(resolved).href));
+    let factory;
+    if (typeof entry.export === 'string') {
+        factory = mod[entry.export];
+        if (typeof factory !== 'function') {
+            throw new Error(`plugin '${entry.plugin}' has no callable export '${entry.export}'`);
+        }
+    }
+    else if (typeof mod.default === 'function') {
+        factory = mod.default;
+    }
+    else {
+        const fns = Object.keys(mod).filter((k) => typeof mod[k] === 'function');
+        if (fns.length === 1) {
+            factory = mod[fns[0]];
+        }
+        else {
+            throw new Error(`plugin '${entry.plugin}' has no default export and ${fns.length} function exports (${fns.join(', ')}); specify "export"`);
+        }
+    }
+    return factory(entry.with ?? entry.options);
+}
+/**
+ * Resolve a slot value: a descriptor is constructed via `loadNamedPlugin`, an
+ * already-constructed plugin passes straight through (backward-compat). Either
+ * way the kind-guard runs, so a wrong-target descriptor still errors.
+ */
+async function resolveSlot(value, kind, configPath) {
+    const resolved = isPluginDescriptor(value)
+        ? await loadNamedPlugin(value, configPath)
+        : value;
+    return requirePlugin(resolved, kind);
+}
+/**
+ * Resolve the `plugins[]` array: descriptor entries are constructed, already-
+ * constructed entries pass through. No kind-guard (plugins are not slotted).
+ */
+async function resolvePlugins(raw, configPath) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const resolved = await Promise.all(raw.map((entry) => isPluginDescriptor(entry) ? loadNamedPlugin(entry, configPath) : entry));
+    return resolved;
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function requireNonEmptyString(value, key) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        throw new Error(`conductor config requires non-empty ${key}`);
+    }
+    return value;
+}
+function optionalPositiveInteger(value, fallback, key) {
+    if (value === undefined) {
+        return fallback;
+    }
+    if (typeof value !== 'number' || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`conductor config requires positive integer ${key}`);
+    }
+    return value;
+}
+/** The conductor config lives at .gaia/conductor.config.js inside a project root. */
+const CONFIG_RELATIVE_PATH = join('.gaia', 'conductor.config.js');
+/**
+ * Resolve the conductor config path from `cwd`. An explicit `--config`
+ * override or `$GAIA_CONDUCTOR_CONFIG` wins verbatim (short-circuit, no
+ * filesystem walk). Otherwise walk from `cwd` root-ward (git/eslint style) to
+ * the nearest ancestor holding `.gaia/conductor.config.js` and return that
+ * absolute path — so any subdirectory of a project/worktree resolves the same
+ * config. If none is found up to the filesystem root, throw a clear, actionable
+ * error instead of leaking a raw "Cannot find module" from a later import().
+ */
+export function resolveConfigPath(override, cwd = process.cwd()) {
+    const explicit = override ?? process.env.GAIA_CONDUCTOR_CONFIG;
+    if (explicit) {
+        return explicit;
+    }
+    let dir = resolve(cwd);
+    for (;;) {
+        const candidate = join(dir, CONFIG_RELATIVE_PATH);
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            break;
+        }
+        dir = parent;
+    }
+    throw new Error(`no .gaia/conductor.config.js found from ${cwd} upward; run \`gaia init\``);
+}
+export async function loadConductorConfig(configFile) {
+    const configPath = resolve(configFile);
+    const module = (await import(pathToFileURL(configPath).href));
+    const raw = module.default;
+    if (!isRecord(raw)) {
+        throw new Error('conductor config default export must be an object');
+    }
+    const config = raw;
+    const site = isRecord(config.site) ? config.site : {};
+    const baseUrl = requireNonEmptyString(site.base_url, 'site.base_url');
+    const project = requireNonEmptyString(config.project, 'project');
+    if (!Array.isArray(config.states) || config.states.length === 0) {
+        throw new Error('conductor config requires non-empty states');
+    }
+    const states = config.states.map((state) => requireNonEmptyString(state, 'states'));
+    const checkoutRoot = dirname(configPath);
+    // Resolve the effective machine_id once (config override or hostname+path
+    // hash) so the id is defined in a single place — the CLI lifecycle commands
+    // and registration all read config.machine_id, never re-derive it. The
+    // conductor label defaults to this id (a conductor is identified by it).
+    const machineId = typeof config.machine_id === 'string' && config.machine_id.trim() !== ''
+        ? config.machine_id
+        : conductorId(checkoutRoot);
+    const label = typeof config.label === 'string' && config.label.trim() !== ''
+        ? config.label
+        : machineId;
+    return {
+        site: {
+            base_url: baseUrl,
+            jsonapi_prefix: typeof site.jsonapi_prefix === 'string' &&
+                site.jsonapi_prefix.trim() !== ''
+                ? site.jsonapi_prefix
+                : '/jsonapi',
+        },
+        ...(Array.isArray(config.plugins)
+            ? { plugins: await resolvePlugins(config.plugins, configPath) }
+            : {}),
+        remote: await resolveSlot(config.remote, 'remote', configPath),
+        executor: await resolveSlot(config.executor, 'executor', configPath),
+        agent: await resolveSlot(config.agent, 'agent', configPath),
+        workspace: await resolveSlot(config.workspace, 'workspace', configPath),
+        label,
+        machine_id: machineId,
+        project,
+        states,
+        prompt: typeof config.prompt === 'string' && config.prompt.trim() !== ''
+            ? config.prompt
+            : DEFAULT_AGENT_PROMPT,
+        max_parallel: optionalPositiveInteger(config.max_parallel, 1, 'max_parallel'),
+        poll_interval_ms: optionalPositiveInteger(config.poll_interval_ms, 5000, 'poll_interval_ms'),
+        lease_seconds: optionalPositiveInteger(config.lease_seconds, 300, 'lease_seconds'),
+        ...(config.hooks !== undefined ? { hooks: config.hooks } : {}),
+        config_path: configPath,
+    };
+}