@gaia-ai/addon-herdr 0.6.1

package/dist/src/pane-layout.d.ts

@@ -0,0 +1,37 @@
+import { type PaneSpec } from './config.js';
+export type HerdrExec = (args: string[], opts?: {
+    redactArgs?: (args: string[]) => string[];
+}) => Promise<string>;
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function parseJson(output: string, command: string): unknown;
+export declare function parsePaneSplit(output: string): string;
+/**
+ * A pane layout: an optional command run in the root/main pane, plus optional
+ * split panes. Shared by the executor's per-run tab (`startRun`) and the
+ * workspace's initial open pane (`herdrWorkspace` `open`) — one code path, no
+ * duplication. The per-state `StateConfig` (executor) and the workspace `open`
+ * option both narrow to this shape (the executor adds `tabLabel`; there is only
+ * one open layout, not a per-state map).
+ */
+export interface PaneLayout {
+    /** Command run in the initial root/main pane (typed verbatim, not templated). */
+    command?: string;
+    /** Extra split panes off the root; each command is `renderTemplate`'d. */
+    panes?: PaneSpec[];
+}
+/**
+ * Apply a {@link PaneLayout} to an existing root pane: run `command` in the root
+ * pane, then split each configured pane (with `--cwd cwd`) and run its
+ * `renderTemplate`'d command. The root command is typed VERBATIM (the caller
+ * pre-assembles it — e.g. the executor's env-prefixed agent command, GAIA-101/128);
+ * only split commands are templated from `vars`.
+ *
+ * `opts.redactCommand` supplies a log-safe rewrite of the root command (env
+ * VALUES masked, key names kept — GAIA-99): when it returns a different string a
+ * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
+ * secret, while the command herdr actually runs stays real. An empty layout
+ * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ */
+export declare function applyPaneLayout(execHerdr: HerdrExec, rootPaneId: string, layout: PaneLayout, cwd: string, vars: Record<string, string>, opts?: {
+    redactCommand?: (command: string) => string;
+}): Promise<void>;

package/dist/src/pane-layout.js

@@ -0,0 +1,69 @@
+import { renderTemplate } from './config.js';
+export function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+export function parseJson(output, command) {
+    try {
+        return JSON.parse(output);
+    }
+    catch {
+        throw new Error(`herdr ${command} returned invalid JSON`);
+    }
+}
+export function parsePaneSplit(output) {
+    const parsed = parseJson(output, 'pane split');
+    const paneId = isRecord(parsed)
+        ? parsed.result?.pane
+            ?.pane_id
+        : undefined;
+    if (typeof paneId !== 'string') {
+        throw new Error('herdr pane split returned invalid schema');
+    }
+    return paneId;
+}
+/**
+ * Apply a {@link PaneLayout} to an existing root pane: run `command` in the root
+ * pane, then split each configured pane (with `--cwd cwd`) and run its
+ * `renderTemplate`'d command. The root command is typed VERBATIM (the caller
+ * pre-assembles it — e.g. the executor's env-prefixed agent command, GAIA-101/128);
+ * only split commands are templated from `vars`.
+ *
+ * `opts.redactCommand` supplies a log-safe rewrite of the root command (env
+ * VALUES masked, key names kept — GAIA-99): when it returns a different string a
+ * `redactArgs` scrubber is passed so a failed `pane run` exec-log never carries a
+ * secret, while the command herdr actually runs stays real. An empty layout
+ * (`{}`) issues no calls at all — the caller's unconfigured default is preserved.
+ */
+export async function applyPaneLayout(execHerdr, rootPaneId, layout, cwd, vars, opts) {
+    if (layout.command) {
+        const command = layout.command;
+        const runArgs = ['pane', 'run', rootPaneId, command];
+        const redacted = opts?.redactCommand?.(command);
+        if (redacted !== undefined && redacted !== command) {
+            await execHerdr(runArgs, {
+                redactArgs: (args) => args.map((a) => (a === command ? redacted : a)),
+            });
+        }
+        else {
+            await execHerdr(runArgs);
+        }
+    }
+    for (const spec of layout.panes ?? []) {
+        const splitPaneId = parsePaneSplit(await execHerdr([
+            'pane',
+            'split',
+            rootPaneId,
+            '--direction',
+            spec.direction,
+            '--cwd',
+            cwd,
+            spec.focus ? '--focus' : '--no-focus',
+        ]));
+        await execHerdr([
+            'pane',
+            'run',
+            splitPaneId,
+            renderTemplate(spec.command, vars),
+        ]);
+    }
+}

package/dist/src/panes.d.ts

@@ -0,0 +1,19 @@
+/** A herdr pane and the tab it sits in. */
+export interface HerdrPaneRef {
+    paneId: string;
+    tabId: string;
+}
+/** A herdr pane plus its label. */
+export interface HerdrPaneInfo extends HerdrPaneRef {
+    label: string;
+}
+/** GAIA_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
+export declare function envArgs(env: Record<string, string | undefined>): string[];
+/** `{ paneId, tabId }` from a `herdr tab create` envelope. */
+export declare function parseTabCreate(output: string): HerdrPaneRef;
+/** `{ paneId, tabId }` from a `result.pane` envelope (pane current / split). */
+export declare function parsePaneInfo(output: string): HerdrPaneRef;
+/** The id of the first tab whose label equals `label`, else null. */
+export declare function findTabIdByLabel(output: string, label: string): string | null;
+/** Panes in `tabId` as `[{ paneId, tabId, label }]` from a `pane list` envelope. */
+export declare function parsePanesInTab(output: string, tabId: string): HerdrPaneInfo[];

package/dist/src/panes.js

@@ -0,0 +1,73 @@
+// Herdr pane/tab CLI envelope parsers (GAIA-190) — the building blocks the
+// intent-level `herdrAgentHost` (agents.ts) uses to talk to herdr. Kept small
+// and herdr-internal; the conductor/TUI never see these pane shapes.
+function isRecord(v) {
+    return typeof v === 'object' && v !== null;
+}
+/** GAIA_* env vars as `--env KEY=VALUE` args (never dump the full environment). */
+export function envArgs(env) {
+    const out = [];
+    for (const [key, value] of Object.entries(env)) {
+        if (key.startsWith('GAIA_') && value != null) {
+            out.push('--env', `${key}=${value}`);
+        }
+    }
+    return out;
+}
+/** `{ paneId, tabId }` from a `herdr tab create` envelope. */
+export function parseTabCreate(output) {
+    const parsed = JSON.parse(output);
+    const result = isRecord(parsed)
+        ? parsed.result
+        : undefined;
+    const paneId = result?.root_pane?.pane_id;
+    const tabId = result?.tab?.tab_id;
+    if (typeof paneId !== 'string' || typeof tabId !== 'string') {
+        throw new Error('herdr tab create returned invalid schema');
+    }
+    return { paneId, tabId };
+}
+/** `{ paneId, tabId }` from a `result.pane` envelope (pane current / split). */
+export function parsePaneInfo(output) {
+    const parsed = JSON.parse(output);
+    const pane = isRecord(parsed)
+        ? parsed.result
+            ?.pane
+        : undefined;
+    const paneId = pane?.pane_id;
+    const tabId = pane?.tab_id;
+    if (typeof paneId !== 'string' || typeof tabId !== 'string') {
+        throw new Error('herdr returned no pane info');
+    }
+    return { paneId, tabId };
+}
+/** The id of the first tab whose label equals `label`, else null. */
+export function findTabIdByLabel(output, label) {
+    const parsed = JSON.parse(output);
+    const tabs = isRecord(parsed)
+        ? parsed.result?.tabs
+        : undefined;
+    if (!Array.isArray(tabs))
+        return null;
+    const match = tabs
+        .filter(isRecord)
+        .find((t) => t.label === label && typeof t.tab_id === 'string');
+    return match ? match.tab_id : null;
+}
+/** Panes in `tabId` as `[{ paneId, tabId, label }]` from a `pane list` envelope. */
+export function parsePanesInTab(output, tabId) {
+    const parsed = JSON.parse(output);
+    const panes = isRecord(parsed)
+        ? parsed.result?.panes
+        : undefined;
+    if (!Array.isArray(panes))
+        return [];
+    return panes
+        .filter(isRecord)
+        .filter((p) => typeof p.pane_id === 'string' && p.tab_id === tabId)
+        .map((p) => ({
+        paneId: p.pane_id,
+        tabId,
+        label: typeof p.label === 'string' ? p.label : '',
+    }));
+}

package/dist/src/preset.d.ts

@@ -0,0 +1,3 @@
+import type { Preset } from '@gaia-ai/conductor/contract';
+export declare const executors: Preset['executors'];
+export declare const workspaces: Preset['workspaces'];

package/dist/src/preset.js

@@ -0,0 +1,9 @@
+import { herdrExecutor, herdrWorkspace } from './index.js';
+export const executors = (acc, opts) => [
+    ...acc,
+    herdrExecutor(opts),
+];
+export const workspaces = (acc, opts) => [
+    ...acc,
+    herdrWorkspace(opts),
+];

package/dist/src/root-anchor.d.ts

@@ -0,0 +1,26 @@
+/** Runs `git <args>` in a cwd; resolves stdout, rejects on non-zero exit. */
+export type RootGitExec = (args: string[], cwd: string) => Promise<string>;
+/** Default git runner for root derivation: real `git` in the given cwd. */
+export declare const defaultRootGitExec: RootGitExec;
+/**
+ * Derive the main-clone root that herdr requires as the `--cwd` for every
+ * `worktree list/open/create`. This is the single anchor shared by BOTH the
+ * `herdrExecutor` and `herdrWorkspace` factories (GAIA-177 AC-3).
+ *
+ * The config path is NOT a safe anchor: `.gaia/` is checked in, so config
+ * discovery walks up to the *worktree-local* config, whose dirname IS the linked
+ * worktree — and herdr rejects a linked worktree as that `--cwd`
+ * (`linked_worktree_source`). Instead ask git: `git rev-parse
+ * --path-format=absolute --git-common-dir`, run from the config dir, always
+ * resolves to the shared main `.git` even from a linked worktree; its parent is
+ * the main clone.
+ *
+ * `override` (a factory `root:` option) always wins and skips git entirely.
+ * Best-effort: a missing `config_path` or a git failure (e.g. not a repo) falls
+ * back to `dirname(config_path)` — the previous behaviour — and finally
+ * `process.cwd()`.
+ */
+export declare function deriveHerdrRoot(configPath: string | undefined, opts?: {
+    override?: string;
+    execGit?: RootGitExec;
+}): Promise<string>;

package/dist/src/root-anchor.js

@@ -0,0 +1,40 @@
+import { dirname } from 'node:path';
+import { exec } from '@gaia-ai/core';
+/** Default git runner for root derivation: real `git` in the given cwd. */
+export const defaultRootGitExec = (args, cwd) => exec('git', args, { cwd });
+/**
+ * Derive the main-clone root that herdr requires as the `--cwd` for every
+ * `worktree list/open/create`. This is the single anchor shared by BOTH the
+ * `herdrExecutor` and `herdrWorkspace` factories (GAIA-177 AC-3).
+ *
+ * The config path is NOT a safe anchor: `.gaia/` is checked in, so config
+ * discovery walks up to the *worktree-local* config, whose dirname IS the linked
+ * worktree — and herdr rejects a linked worktree as that `--cwd`
+ * (`linked_worktree_source`). Instead ask git: `git rev-parse
+ * --path-format=absolute --git-common-dir`, run from the config dir, always
+ * resolves to the shared main `.git` even from a linked worktree; its parent is
+ * the main clone.
+ *
+ * `override` (a factory `root:` option) always wins and skips git entirely.
+ * Best-effort: a missing `config_path` or a git failure (e.g. not a repo) falls
+ * back to `dirname(config_path)` — the previous behaviour — and finally
+ * `process.cwd()`.
+ */
+export async function deriveHerdrRoot(configPath, opts = {}) {
+    if (opts.override !== undefined) {
+        return opts.override;
+    }
+    const configDir = configPath ? dirname(configPath) : undefined;
+    const fallback = configDir ?? process.cwd();
+    if (configDir === undefined) {
+        return fallback;
+    }
+    const execGit = opts.execGit ?? defaultRootGitExec;
+    try {
+        const commonDir = (await execGit(['rev-parse', '--path-format=absolute', '--git-common-dir'], configDir)).trim();
+        return commonDir ? dirname(commonDir) : fallback;
+    }
+    catch {
+        return fallback;
+    }
+}

package/dist/src/workspace.d.ts

@@ -0,0 +1,85 @@
+import type { EnsuredWorkspace, GaiaWorkspace, WorkspacePlugin } from '@gaia-ai/conductor/contract';
+import type { ConductorLogger } from '@gaia-ai/core';
+import type { AgentLaunchHost } from './agent-host.js';
+import type { PaneSpec } from './config.js';
+import { type RootGitExec } from './root-anchor.js';
+export type HerdrExec = (args: string[]) => Promise<string>;
+export type GitExec = (args: string[]) => Promise<string>;
+/**
+ * Layout applied to the workspace's initial (root) pane on a FRESH worktree open
+ * (GAIA-139): `command` launches a tool in the main pane (e.g. `spiceedit`) so
+ * the human lands in an editor instead of a bare shell; `panes[]` are optional
+ * splits off it. Same shape as the executor's per-state layout minus `tabLabel`
+ * — there is only ONE open layout, not a per-ticket-state map. Unset → the bare
+ * empty tab opens unchanged (the current good default).
+ */
+export interface OpenLayout {
+    command?: string;
+    panes?: PaneSpec[];
+}
+export interface HerdrWorkspaceOptions {
+    /** Main clone (a git repo): herdr `--cwd` target + worktree base. */
+    root: string;
+    /** Relative dir (under root) for new worktrees. Default: `.gaia-worktrees`. */
+    worktreeDir?: string;
+    /**
+     * Base ref new worktree branches are created from. Default: the remote
+     * tracking branch of the repo's checked-out branch (e.g. `origin/develop`),
+     * so runs start from the pushed remote state, not the host's local branch.
+     */
+    baseBranch?: string;
+    /**
+     * Startup layout for the initial pane, applied on a FRESH worktree open only
+     * (GAIA-139). Unset → the bare empty tab is left unchanged.
+     */
+    open?: OpenLayout;
+    /** Overrideable herdr exec fn — defaults to the real `herdr` binary. */
+    execHerdr?: HerdrExec;
+    /** Overrideable git exec fn — defaults to the real `git` binary. */
+    execGit?: GitExec;
+    /** Optional logger for the best-effort open-layout path (defaults to noop). */
+    logger?: ConductorLogger;
+}
+export declare class HerdrWorkspace implements GaiaWorkspace {
+    private readonly options;
+    private readonly execHerdr;
+    private readonly execGit;
+    private readonly root;
+    private readonly worktreeDir;
+    private readonly open;
+    private readonly logger;
+    /** Herdr-backed intent-level agent host for `gaia ui` (GAIA-190). */
+    readonly agentHost: AgentLaunchHost;
+    constructor(options: HerdrWorkspaceOptions);
+    /**
+     * Resolve the base ref for a new worktree branch. Prefers the configured
+     * `baseBranch`; otherwise the remote tracking branch of the repo's HEAD
+     * (e.g. `origin/develop`). Best-effort: a repo with no upstream returns
+     * `undefined`, leaving herdr to fall back to the parent workspace HEAD.
+     */
+    private resolveBaseRef;
+    /**
+     * Fetch the base ref's remote branch so the new worktree starts from the
+     * latest pushed state. Best-effort: offline / unknown remote is non-fatal.
+     */
+    private fetchBaseRef;
+    /**
+     * Verify a base-ref candidate resolves on the remote (after fetching it).
+     * Returns the ref when it exists, else undefined so the caller falls back.
+     */
+    private verifyRemoteRef;
+    ensure(_identifier: string, branch?: string, baseRefOverride?: string): Promise<EnsuredWorkspace>;
+}
+export declare function herdrWorkspace(opts?: {
+    /**
+     * Explicit repo-root override; wins over the git-derived anchor. Otherwise
+     * the main clone is derived from the git common dir (GAIA-177).
+     */
+    root?: string;
+    worktreeDir?: string;
+    baseBranch?: string;
+    open?: OpenLayout;
+    /** Overrideable git exec for root derivation (tests). */
+    execGit?: RootGitExec;
+}): WorkspacePlugin;
+export default herdrWorkspace;

package/dist/src/workspace.js

@@ -0,0 +1,261 @@
+import { resolve } from 'node:path';
+import { loadInstructions } from '@gaia-ai/addon-workspace-git';
+import { exec } from '@gaia-ai/core';
+import { herdrAgentHost } from './agents.js';
+import { applyPaneLayout, isRecord, parseJson } from './pane-layout.js';
+import { deriveHerdrRoot } from './root-anchor.js';
+const defaultExec = (args) => exec('herdr', args);
+const defaultGitExec = (args) => exec('git', args);
+const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+/** Parse `herdr worktree list --json` → array of on-disk worktrees. */
+function parseWorktreeList(output) {
+    const parsed = parseJson(output, 'worktree list');
+    const worktrees = isRecord(parsed)
+        ? parsed.result?.worktrees
+        : undefined;
+    if (!Array.isArray(worktrees)) {
+        throw new Error('herdr worktree list returned invalid schema');
+    }
+    return worktrees
+        .filter(isRecord)
+        .filter((w) => typeof w.branch === 'string' && typeof w.path === 'string')
+        .map((w) => ({
+        branch: w.branch,
+        path: w.path,
+        ...(typeof w.open_workspace_id === 'string'
+            ? { open_workspace_id: w.open_workspace_id }
+            : {}),
+    }));
+}
+/** Parse `worktree create`/`worktree open` → the created/opened worktree path. */
+function parseWorktreePath(output, command) {
+    const parsed = parseJson(output, command);
+    const path = isRecord(parsed)
+        ? parsed.result?.worktree
+            ?.path
+        : undefined;
+    if (typeof path !== 'string') {
+        throw new Error(`herdr ${command} returned invalid schema`);
+    }
+    return path;
+}
+/**
+ * Parse `worktree create` → the created tab's root pane id
+ * (`result.root_pane.pane_id`), sibling of {@link parseWorktreePath}. Returns
+ * null when the create JSON carries none, so the open-layout caller can skip
+ * silently rather than throw (best-effort).
+ */
+function parseWorktreeRootPane(output) {
+    const parsed = parseJson(output, 'worktree create');
+    const paneId = isRecord(parsed)
+        ? parsed.result
+            ?.root_pane?.pane_id
+        : undefined;
+    return typeof paneId === 'string' && paneId ? paneId : null;
+}
+/** Git-safe branch validation: safe ref chars only, no leading dot, no `..`. */
+function validateBranch(branch) {
+    if (!/^[A-Za-z0-9._/-]+$/.test(branch) ||
+        branch.startsWith('.') ||
+        branch.includes('..')) {
+        throw new Error(`invalid workspace branch: ${branch}`);
+    }
+}
+export class HerdrWorkspace {
+    options;
+    execHerdr;
+    execGit;
+    root;
+    worktreeDir;
+    open;
+    logger;
+    /** Herdr-backed intent-level agent host for `gaia ui` (GAIA-190). */
+    agentHost;
+    constructor(options) {
+        this.options = options;
+        this.execHerdr = options.execHerdr ?? defaultExec;
+        this.execGit = options.execGit ?? defaultGitExec;
+        this.root = resolve(options.root);
+        this.worktreeDir = options.worktreeDir ?? '.gaia-worktrees';
+        this.open = options.open;
+        this.logger = options.logger ?? noopLogger;
+        this.agentHost = herdrAgentHost(this.execHerdr);
+    }
+    /**
+     * Resolve the base ref for a new worktree branch. Prefers the configured
+     * `baseBranch`; otherwise the remote tracking branch of the repo's HEAD
+     * (e.g. `origin/develop`). Best-effort: a repo with no upstream returns
+     * `undefined`, leaving herdr to fall back to the parent workspace HEAD.
+     */
+    async resolveBaseRef() {
+        if (this.options.baseBranch) {
+            return this.options.baseBranch;
+        }
+        try {
+            const ref = (await this.execGit([
+                '-C',
+                this.root,
+                'rev-parse',
+                '--abbrev-ref',
+                '--symbolic-full-name',
+                '@{u}',
+            ])).trim();
+            return ref || undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Fetch the base ref's remote branch so the new worktree starts from the
+     * latest pushed state. Best-effort: offline / unknown remote is non-fatal.
+     */
+    async fetchBaseRef(baseRef) {
+        const slash = baseRef.indexOf('/');
+        if (slash <= 0) {
+            return;
+        }
+        const remote = baseRef.slice(0, slash);
+        const branch = baseRef.slice(slash + 1);
+        try {
+            await this.execGit(['-C', this.root, 'fetch', remote, branch]);
+        }
+        catch {
+            // Non-fatal: use whatever the local tracking ref already points at.
+        }
+    }
+    /**
+     * Verify a base-ref candidate resolves on the remote (after fetching it).
+     * Returns the ref when it exists, else undefined so the caller falls back.
+     */
+    async verifyRemoteRef(ref) {
+        await this.fetchBaseRef(ref);
+        try {
+            await this.execGit([
+                '-C',
+                this.root,
+                'rev-parse',
+                '--verify',
+                '--quiet',
+                `${ref}^{commit}`,
+            ]);
+            return ref;
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async ensure(_identifier, branch, baseRefOverride) {
+        if (branch === undefined) {
+            throw new Error('herdr workspace requires a branch name');
+        }
+        validateBranch(branch);
+        const worktrees = parseWorktreeList(await this.execHerdr(['worktree', 'list', '--cwd', this.root, '--json']));
+        const existing = worktrees.find((w) => w.branch === branch);
+        if (existing) {
+            // Reuse: an existing worktree is never re-created, so created=false — the
+            // core skips the after_create hook for it. The open layout is NOT
+            // re-applied on reuse (GAIA-139): no duplicate editor process on reattach.
+            let path = existing.path;
+            if (!existing.open_workspace_id) {
+                // On-disk worktree with no open herdr workspace — open it.
+                path = parseWorktreePath(await this.execHerdr([
+                    'worktree',
+                    'open',
+                    '--cwd',
+                    this.root,
+                    '--branch',
+                    branch,
+                    '--no-focus',
+                    '--json',
+                ]), 'worktree open');
+            }
+            return { path, instructions: loadInstructions(path), created: false };
+        }
+        // Fresh: create the git worktree + herdr workspace in one call. Base the
+        // new branch on the (freshly fetched) remote tracking branch, not the
+        // host's local checked-out branch. A ticket passes its `origin/<base_branch>`
+        // as the override; use it only when it resolves on the remote, else fall
+        // back to the default base.
+        let baseRef;
+        if (baseRefOverride !== undefined) {
+            baseRef = await this.verifyRemoteRef(baseRefOverride);
+        }
+        if (baseRef === undefined) {
+            baseRef = await this.resolveBaseRef();
+            if (baseRef !== undefined) {
+                await this.fetchBaseRef(baseRef);
+            }
+        }
+        const createOutput = await this.execHerdr([
+            'worktree',
+            'create',
+            '--cwd',
+            this.root,
+            '--branch',
+            branch,
+            ...(baseRef !== undefined ? ['--base', baseRef] : []),
+            '--label',
+            branch,
+            // ABSOLUTE, never relative: herdr canonicalizes a relative `--path`
+            // against its own `current_dir()`, which fails with
+            // `Os { code: 2, kind: NotFound }` whenever the CALLER's cwd has been
+            // deleted — e.g. a conductor still polling from a reaped worktree. That
+            // killed every dispatch with an unattributable herdr exit 1. `resolve`
+            // (not `join`) so an absolute `worktreeDir` override still wins.
+            '--path',
+            resolve(this.root, this.worktreeDir, branch),
+            '--no-focus',
+            '--json',
+        ]);
+        const path = parseWorktreePath(createOutput, 'worktree create');
+        // GAIA-139: on a FRESH create, apply the configured open layout to the
+        // initial root pane (launch e.g. `spiceedit` instead of a bare shell). The
+        // pane's cwd is the worktree checkout, passed explicitly on the splits (the
+        // root pane's cwd is already the checkout). Best-effort — mirrors the
+        // `fetchBaseRef` pattern above: a broken layout is logged and swallowed so a
+        // startup-command failure can NEVER wedge worktree creation / run dispatch.
+        if (this.open) {
+            try {
+                const rootPaneId = parseWorktreeRootPane(createOutput);
+                if (rootPaneId) {
+                    await applyPaneLayout(this.execHerdr, rootPaneId, this.open, path, {
+                        branch,
+                        worktreePath: path,
+                    });
+                }
+            }
+            catch (err) {
+                this.logger.warn({ branch, worktree: path, err: String(err) }, 'herdr open-layout failed (best-effort, ignored)');
+            }
+        }
+        // The `after_create` hook is run by the executor (GAIA-84), not here — the
+        // workspace only reports that it created a fresh worktree.
+        return { path, instructions: loadInstructions(path), created: true };
+    }
+}
+export function herdrWorkspace(opts = {}) {
+    return {
+        kind: 'workspace',
+        id: 'herdr',
+        requiredModules: [],
+        async createWorkspace(config) {
+            const root = await deriveHerdrRoot(config.config_path, {
+                ...(opts.root !== undefined ? { override: opts.root } : {}),
+                ...(opts.execGit ? { execGit: opts.execGit } : {}),
+            });
+            return new HerdrWorkspace({
+                root,
+                ...(opts.worktreeDir ? { worktreeDir: opts.worktreeDir } : {}),
+                ...(opts.baseBranch ? { baseBranch: opts.baseBranch } : {}),
+                ...(opts.open ? { open: opts.open } : {}),
+            });
+        },
+    };
+}
+export default herdrWorkspace;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@gaia-ai/addon-herdr",
+  "version": "0.6.1",
+  "description": "GAIA herdr integration: spawn executor + per-ticket worktree workspace.",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": "./dist/src/index.js",
+    "./preset": "./dist/src/preset.js"
+  },
+  "files": [
+    "dist/src"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://git.key-tec.de/keytec/gaia.git",
+    "directory": "gaia-cli/addons/herdr"
+  },
+  "dependencies": {
+    "@gaia-ai/addon-workspace-git": "^0.6.1"
+  },
+  "peerDependencies": {
+    "@gaia-ai/conductor": "^0.6.1",
+    "@gaia-ai/core": "^0.6.1"
+  }
+}