@gaia-ai/addon-herdr 0.6.1

package/dist/src/index.js

@@ -0,0 +1,708 @@
+import { existsSync } from 'node:fs';
+import { exec, shellQuote, slugify } from '@gaia-ai/core';
+import { resolveStateConfig, } from './config.js';
+import { forceRemoveDir, restoreWritable } from './fs.js';
+import { applyPaneLayout, isRecord, parseJson, } from './pane-layout.js';
+import { deriveHerdrRoot } from './root-anchor.js';
+export { herdrAgentHost } from './agents.js';
+export { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
+// GAIA-139: the herdr workspace lives in the same package now (the separate
+// @gaia-ai/addon-herdr-workspace was merged in). The package DEFAULT export
+// stays the executor (below); herdrWorkspace + HerdrWorkspace are named exports.
+export { HerdrWorkspace, herdrWorkspace, } from './workspace.js';
+async function defaultExec(args, opts) {
+    return exec('herdr', args, opts);
+}
+/** Default git runner: real `git` in the given cwd (the parent repo root). */
+const defaultGitRunner = (args, cwd) => exec('git', args, { cwd });
+/**
+ * Parse `git worktree list --porcelain`. Records are blank-line separated; each
+ * has a `worktree <path>` line and, for an attached HEAD, a `branch
+ * refs/heads/<branch>` line (a detached HEAD has none). `prunable <reason>`
+ * entries (a `.git/worktrees/<name>` admin entry whose dir has vanished) still
+ * carry their `worktree <path>` line, so they parse too — the caller decides
+ * what to do with a path no longer on disk.
+ */
+function parseGitWorktreePorcelain(output) {
+    const entries = [];
+    let path = null;
+    let branch = null;
+    const flush = () => {
+        if (path) {
+            entries.push({ path, branch });
+        }
+        path = null;
+        branch = null;
+    };
+    for (const line of output.split('\n')) {
+        if (line.startsWith('worktree ')) {
+            flush(); // a new record begins — commit the previous one
+            path = line.slice('worktree '.length).trim();
+        }
+        else if (line.startsWith('branch ')) {
+            branch = line
+                .slice('branch '.length)
+                .trim()
+                .replace(/^refs\/heads\//, '');
+        }
+    }
+    flush();
+    return entries;
+}
+/** Default hook runner: `sh -c <command>` in the worktree — fails honestly. */
+const defaultShellRunner = async (command, cwd, env) => {
+    await exec('sh', ['-c', command], { cwd, ...(env ? { env } : {}) });
+};
+const noopLogger = {
+    debug() { },
+    info() { },
+    warn() { },
+    error() { },
+};
+function parseWorktreeList(output) {
+    const parsed = parseJson(output, 'worktree list');
+    const worktrees = isRecord(parsed)
+        ? parsed.result?.worktrees
+        : undefined;
+    if (!Array.isArray(worktrees)) {
+        return [];
+    }
+    // Key on `path` only — herdr reports `branch: null` for a detached HEAD, and
+    // the branch is mutable anyway (see resolveWorktreeEntry). Dropping such
+    // entries is exactly the GAIA-114 defect: the worktree becomes invisible to
+    // a path lookup.
+    return worktrees
+        .filter(isRecord)
+        .filter((w) => typeof w.path === 'string')
+        .map((w) => ({
+        branch: typeof w.branch === 'string' ? w.branch : null,
+        path: w.path,
+        ...(typeof w.open_workspace_id === 'string' && w.open_workspace_id
+            ? { open_workspace_id: w.open_workspace_id }
+            : {}),
+    }));
+}
+/**
+ * Parse `herdr workspace list` (which always emits JSON; it takes no `--json`
+ * flag). Enumerates every workspace on the host with its `focused` flag and its
+ * `worktree.{is_linked_worktree,repo_root}` — the inputs the GAIA-166 focus
+ * guard needs to tell a focused ticket worktree from its main-checkout sibling.
+ */
+function parseWorkspaceList(output) {
+    const parsed = parseJson(output, 'workspace list');
+    const workspaces = isRecord(parsed)
+        ? parsed.result?.workspaces
+        : undefined;
+    if (!Array.isArray(workspaces)) {
+        return [];
+    }
+    return workspaces
+        .filter(isRecord)
+        .filter((w) => typeof w.workspace_id === 'string')
+        .map((w) => {
+        const wt = isRecord(w.worktree) ? w.worktree : undefined;
+        return {
+            workspaceId: w.workspace_id,
+            focused: w.focused === true,
+            isLinkedWorktree: wt?.is_linked_worktree === true,
+            repoRoot: typeof wt?.repo_root === 'string' ? wt.repo_root : null,
+        };
+    });
+}
+/**
+ * Extract the open workspace id from `herdr worktree open`'s own JSON. herdr
+ * returns it in the result envelope under any of these keys (herdr 0.7.x):
+ * `workspace.workspace_id`, `worktree.open_workspace_id`, or
+ * `root_pane.workspace_id`. Returns null when the payload carries none (e.g. an
+ * error envelope), so the caller can fall back to a list lookup or surface the
+ * failure. This is the reliable success path — no branch match involved.
+ */
+function parseWorkspaceOpen(output) {
+    const parsed = parseJson(output, 'worktree open');
+    const result = isRecord(parsed)
+        ? parsed.result
+        : undefined;
+    const candidates = [
+        result?.workspace?.workspace_id,
+        result?.worktree?.open_workspace_id,
+        result?.root_pane?.workspace_id,
+    ];
+    for (const c of candidates) {
+        if (typeof c === 'string' && c) {
+            return c;
+        }
+    }
+    return null;
+}
+function parseTabList(output) {
+    const parsed = parseJson(output, 'tab list');
+    const tabs = isRecord(parsed)
+        ? parsed.result?.tabs
+        : undefined;
+    if (!Array.isArray(tabs)) {
+        return [];
+    }
+    return tabs
+        .filter(isRecord)
+        .filter((t) => typeof t.tab_id === 'string' && typeof t.label === 'string')
+        .map((t) => ({
+        tabId: t.tab_id,
+        label: t.label,
+    }));
+}
+/**
+ * Whether a tab label carries the exact `#<runId>` token that `startRun` emits
+ * (`<identifier> · <state> #<run.id>`). Anchored on the trailing token and
+ * compared numerically, so `#4339` never matches `#43390` / `#433` (GAIA-183
+ * AC-3). A label with no trailing `#<digits>` token (a non-run tab) never
+ * matches.
+ */
+function labelMatchesRun(label, runId) {
+    const m = label.match(/#(\d+)$/);
+    return m !== null && Number(m[1]) === runId;
+}
+function parseTabCreate(output) {
+    const parsed = parseJson(output, 'tab create');
+    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 };
+}
+/** Normalise a worktree path for comparison (strip trailing slashes). */
+function normPath(path) {
+    return path.replace(/\/+$/, '');
+}
+/**
+ * Resolve a worktree entry, preferring the stable `worktreePath` over `branch`.
+ * The checked-out branch is mutable (the coding agent may rename/switch it), so
+ * the path — deterministic and identifier-derived — is the reliable key. Fall
+ * back to a branch match so a missing/renamed path still resolves. Returns null
+ * only when neither key matches any listed worktree.
+ */
+function resolveWorktreeEntry(entries, branch, worktreePath) {
+    if (worktreePath) {
+        const want = normPath(worktreePath);
+        const byPath = entries.find((e) => normPath(e.path) === want);
+        if (byPath) {
+            return byPath;
+        }
+    }
+    return entries.find((e) => e.branch === branch) ?? null;
+}
+export class HerdrExecutor {
+    options;
+    execHerdr;
+    logger;
+    runShell;
+    runGit;
+    id = 'herdr';
+    constructor(options, execHerdr = defaultExec, logger = noopLogger, runShell = defaultShellRunner, runGit = defaultGitRunner) {
+        this.options = options;
+        this.execHerdr = execHerdr;
+        this.logger = logger;
+        this.runShell = runShell;
+        this.runGit = runGit;
+    }
+    capabilities() {
+        return { persistent: true };
+    }
+    /**
+     * Run the lifecycle hook `name` best-effort — the single catch point for all
+     * lifecycle hooks (see {@link GaiaExecutor.runHook}). No configured command →
+     * silent no-op. A failing command → log loudly (hook + worktree + ticket +
+     * err) and return. NEVER throws, so a hook failure can't abort dispatch or
+     * wedge a run.
+     */
+    async runHook(name, cwd, ctx, env) {
+        const command = this.options.hooks?.[name];
+        if (!command) {
+            return;
+        }
+        try {
+            await this.runShell(command, cwd, env);
+        }
+        catch (err) {
+            this.logger.error({ hook: name, worktree: cwd, ticket: ctx.ticket, err: String(err) }, 'lifecycle hook failed');
+        }
+    }
+    /**
+     * List worktrees, ALWAYS anchored to the configured parent repo root
+     * (GAIA-211). `herdr worktree list` is machine-global, but run WITHOUT
+     * `--cwd` it resolves herdr's own ambient (previously selected / persisted /
+     * process / shell / daemon) repository context. When a preceding
+     * `gaia-cleanup-*` integration test selected then deleted a
+     * `/tmp/gaia-cleanup-*` repo, that stale context survives and the unanchored
+     * list exits (`cannot change to '/tmp/gaia-cleanup-…'`), aborting dispatch.
+     * Anchoring every list with `--cwd this.options.root` makes listing
+     * independent of that ambient context. This is the SINGLE choke point for
+     * all executor `worktree list` call paths — the sibling
+     * {@link HerdrWorkspace.ensure} anchors identically. The `--cwd` is only
+     * omitted when no root is configured (rootless test callers).
+     *
+     * On a herdr failure it throws an error naming the explicit configured root
+     * and the operation (AC-9) instead of surfacing herdr's raw stale-context
+     * message, so a future context failure is diagnosable.
+     */
+    async listWorktrees() {
+        const args = [
+            'worktree',
+            'list',
+            ...(this.options.root ? ['--cwd', this.options.root] : []),
+            '--json',
+        ];
+        let output;
+        try {
+            output = await this.execHerdr(args);
+        }
+        catch (err) {
+            throw new Error(`herdr worktree list failed for configured root ${this.options.root ?? '<unset>'}: ${String(err)}`);
+        }
+        return parseWorktreeList(output);
+    }
+    /**
+     * Find the worktree entry (path + open_workspace_id) for a branch via
+     * worktree list. Returns null if the branch has no worktree.
+     */
+    async findWorktreeByBranch(branch) {
+        const entries = await this.listWorktrees();
+        return entries.find((e) => e.branch === branch) ?? null;
+    }
+    /**
+     * Find the open_workspace_id for a branch via worktree list.
+     * Returns null if no workspace is open for that branch.
+     */
+    async findWorkspaceByBranch(branch) {
+        const entry = await this.findWorktreeByBranch(branch);
+        return entry?.open_workspace_id ?? null;
+    }
+    /**
+     * Find the open_workspace_id for a worktree by its stable `worktreePath`
+     * (falling back to `branch`; see {@link resolveWorktreeEntry}). Unlike
+     * {@link findWorkspaceByBranch}, this does not rely on the mutable branch —
+     * it is the startRun lookup the GAIA-114 fix hangs on. Returns null when the
+     * worktree is not listed as open.
+     */
+    async findOpenWorkspace(branch, worktreePath) {
+        const entries = await this.listWorktrees();
+        return (resolveWorktreeEntry(entries, branch, worktreePath)?.open_workspace_id ??
+            null);
+    }
+    /** Parent repo root for git worktree admin ops (falls back to `fallback`). */
+    gitRoot(fallback) {
+        return this.options.root ?? fallback;
+    }
+    /**
+     * Sweep orphaned `.git/worktrees/<name>` admin entries at the parent repo
+     * root — the ones whose on-disk dir has vanished (GAIA-141: they show up as
+     * `prunable` in `git worktree list`). Best-effort: a prune failure must never
+     * fail teardown.
+     */
+    async pruneWorktrees(root) {
+        try {
+            await this.runGit(['worktree', 'prune'], root);
+        }
+        catch {
+            // best-effort — pruning is a sweep, never the teardown's success gate
+        }
+    }
+    /**
+     * Remove an on-disk worktree GIT-AWARELY (GAIA-141 RC-1). The old fallback
+     * raw-`rm`'d the directory and left the parent repo's `.git/worktrees/<name>`
+     * admin entry behind → a `prunable` orphan. This:
+     *   1. restores owner-write (Drupal hardens web/sites/default 0555 +
+     *      settings.php 0444 — chmod-restorable by the owning user, no sudo);
+     *   2. `git worktree remove --force <path>` from the PARENT repo root, which
+     *      unlinks the directory AND drops the `.git/worktrees/<name>` entry;
+     *   3. guarantees the directory is gone (a raw force-remove) in case git
+     *      refused (the path was never a registered worktree) — a no-op if git
+     *      already removed it;
+     *   4. prunes the repo so any now-stale admin entry is swept.
+     */
+    async gitAwareRemove(path) {
+        restoreWritable(path);
+        const root = this.gitRoot(path);
+        try {
+            await this.runGit(['worktree', 'remove', '--force', path], root);
+        }
+        catch {
+            // Not a registered worktree (or git refused) — reclaim the dir directly.
+        }
+        if (existsSync(path)) {
+            forceRemoveDir(path);
+        }
+        await this.pruneWorktrees(root);
+    }
+    /**
+     * When herdr has lost track of a worktree and its `worktreePath` was never
+     * persisted, the PARENT repo's `git worktree list` still knows it (GAIA-141
+     * RC-2 — the ~28 never-touched leftovers). Resolve the lost worktree's on-disk
+     * path there, preferring an exact `worktreePath` match, then a branch match;
+     * never the main worktree (the repo root itself). Returns null when nothing
+     * matches. Best-effort: a git failure resolves to null.
+     */
+    async findGitWorktree(root, branch, worktreePath) {
+        let output;
+        try {
+            output = await this.runGit(['worktree', 'list', '--porcelain'], root);
+        }
+        catch {
+            return null;
+        }
+        const candidates = parseGitWorktreePorcelain(output).filter((e) => normPath(e.path) !== normPath(root));
+        if (worktreePath) {
+            const want = normPath(worktreePath);
+            const byPath = candidates.find((e) => normPath(e.path) === want);
+            if (byPath) {
+                return byPath.path;
+            }
+        }
+        return candidates.find((e) => e.branch === branch)?.path ?? null;
+    }
+    /**
+     * GAIA-166 focus guard. herdr's `worktree remove` deletes the ticket
+     * worktree's on-disk directory; if that workspace is the CURRENTLY FOCUSED
+     * one, the interactive client is left in a now-deleted `cwd` and herdr spawns
+     * a stray empty workspace for the dead path. So before the remove, if the
+     * target workspace is focused, switch focus to the main-checkout (non-linked)
+     * workspace of the SAME repo. A background reap of a non-focused worktree
+     * (or one herdr no longer lists) focuses nothing.
+     *
+     * Returns whether it is SAFE to proceed with the remove: `false` when a
+     * required focus switch cannot be resolved or verified — the caller then
+     * aborts (returns `false` → `cleaned_up=0`) so the reaper retries later,
+     * rather than deleting the focused path out from under the user.
+     */
+    async ensureFocusSafeToRemove(workspaceId) {
+        const workspaces = parseWorkspaceList(await this.execHerdr(['workspace', 'list']));
+        const target = workspaces.find((w) => w.workspaceId === workspaceId);
+        // Not focused (or not listed) → removing it strands no client.
+        if (!target?.focused) {
+            return true;
+        }
+        // Focused: resolve the main-checkout workspace for the SAME repo — the
+        // non-linked workspace whose repo_root matches the target's (falling back
+        // to the configured parent root when herdr reports no repo_root).
+        const anchor = target.repoRoot ?? this.options.root ?? null;
+        const parent = anchor === null
+            ? undefined
+            : workspaces.find((w) => w.workspaceId !== workspaceId &&
+                !w.isLinkedWorktree &&
+                w.repoRoot !== null &&
+                normPath(w.repoRoot) === normPath(anchor));
+        // No safe target → do NOT delete the focused path; retry later.
+        if (!parent) {
+            return false;
+        }
+        try {
+            await this.execHerdr(['workspace', 'focus', parent.workspaceId]);
+        }
+        catch {
+            return false;
+        }
+        // Verify the switch actually took before deleting the (was-focused) dir.
+        const after = parseWorkspaceList(await this.execHerdr(['workspace', 'list']));
+        const parentNow = after.find((w) => w.workspaceId === parent.workspaceId);
+        const targetNow = after.find((w) => w.workspaceId === workspaceId);
+        return parentNow?.focused === true && targetNow?.focused !== true;
+    }
+    /**
+     * Tear down a ticket's entire worktree (git worktree + hosted workspace).
+     * `herdr worktree remove` is keyed by an open workspace id, so resolve the
+     * worktree first — by its stable `worktreePath`, falling back to `branch`
+     * (see {@link resolveWorktreeEntry}): if its workspace is already open use
+     * that id; otherwise open the on-disk worktree to obtain one (mirrors
+     * startRun's open-if-needed).
+     *
+     * `herdr worktree list` is machine-global — it enumerates every repo's
+     * worktrees on the host, most of which are not ours. So a no-match does NOT
+     * mean "error"; it means herdr no longer tracks this ticket's worktree. When
+     * herdr has lost track, teardown is resolved off git itself (never a foreign
+     * worktree), git-awarely so no `.git/worktrees/<name>` metadata is orphaned
+     * (GAIA-141 RC-1):
+     *   - `worktreePath` still on disk → reclaim it git-awarely;
+     *   - `worktreePath` known but gone from disk → already torn down; sweep any
+     *     orphaned metadata and report verified;
+     *   - `worktreePath` unknown → resolve the lost worktree via the parent repo's
+     *     `git worktree list` (GAIA-141 RC-2) and reclaim it git-awarely.
+     *
+     * Returns whether the teardown was VERIFIED on THIS host: `true` when the
+     * worktree is gone (removed by us, an on-disk orphan reclaimed, or confirmed
+     * already absent), `false` ONLY when nothing was resolvable and the teardown
+     * could not be verified — the reaper then leaves the ticket on its work list
+     * for a later retry instead of falsely flagging it cleaned (GAIA-141 RC-2).
+     */
+    async removeWorktree(branch, worktreePath) {
+        const entries = await this.listWorktrees();
+        const entry = resolveWorktreeEntry(entries, branch, worktreePath);
+        if (!entry) {
+            // herdr no longer tracks it. Resolve teardown off git, never a foreign
+            // worktree, and git-awarely so no `.git/worktrees/<name>` is orphaned.
+            if (worktreePath && existsSync(worktreePath)) {
+                await this.gitAwareRemove(worktreePath);
+                return true;
+            }
+            if (worktreePath) {
+                // Path known but already gone from disk → verified (idempotent) teardown;
+                // still sweep any orphaned metadata it left behind.
+                if (this.options.root) {
+                    await this.pruneWorktrees(this.options.root);
+                }
+                return true;
+            }
+            // Path unknown (never persisted). The parent repo's git worktree list may
+            // still know the lost worktree — resolve + reclaim it (GAIA-141 RC-2).
+            if (this.options.root) {
+                const gitPath = await this.findGitWorktree(this.options.root, branch);
+                if (gitPath) {
+                    await this.gitAwareRemove(gitPath);
+                    return true;
+                }
+                // Nothing resolvable — sweep pre-existing orphans, then report the
+                // teardown UNVERIFIED so the reaper retries rather than falsely cleaning.
+                await this.pruneWorktrees(this.options.root);
+            }
+            return false;
+        }
+        let workspaceId = entry.open_workspace_id ?? null;
+        if (!workspaceId) {
+            // Reattach from the PARENT repo root, never the linked worktree itself:
+            // herdr rejects an open whose --cwd is a linked worktree with
+            // `linked_worktree_source` ("New and open actions start from the repo
+            // parent workspace"), which then yields no workspace id and the remove
+            // never runs. Fall back to the linked path only when no root is
+            // configured (keeps the old behaviour for rootless test callers).
+            await this.execHerdr([
+                'worktree',
+                'open',
+                '--cwd',
+                this.options.root ?? entry.path,
+                '--branch',
+                // entry.branch is null for a detached HEAD; fall back to the ticket
+                // branch so `open` still gets a branch arg.
+                entry.branch ?? branch,
+                '--no-focus',
+                '--json',
+            ]);
+            // Re-resolve by the same keys — open flips the entry's workspace id.
+            const reopened = resolveWorktreeEntry(await this.listWorktrees(), branch, worktreePath);
+            workspaceId = reopened?.open_workspace_id ?? null;
+            if (!workspaceId) {
+                throw new Error(`herdr worktree open did not yield a workspace id for path ${entry.path} (branch ${entry.branch})`);
+            }
+        }
+        // GAIA-166: before deleting the worktree's directory, if its workspace is
+        // the focused one, move focus to the main checkout — else the client is
+        // stranded in a deleted cwd. If a needed focus switch can't be made safely,
+        // abort UNVERIFIED so the reaper retries rather than stranding the user.
+        if (!(await this.ensureFocusSafeToRemove(workspaceId))) {
+            return false;
+        }
+        // Drupal hardens web/sites/default (0555) and settings.php/.htaccess (0444);
+        // herdr's remove performs the actual unlink and would hit EACCES on those
+        // read-only dirs. Restore owner-write on the on-disk worktree first.
+        restoreWritable(entry.path);
+        await this.execHerdr([
+            'worktree',
+            'remove',
+            '--workspace',
+            workspaceId,
+            '--force',
+            '--json',
+        ]);
+        // GAIA-166: verify the directory is actually gone on disk. If it survived,
+        // report the teardown UNVERIFIED (false) so the reaper retries instead of
+        // falsely flagging the ticket cleaned.
+        if (existsSync(entry.path)) {
+            return false;
+        }
+        // Sweep any orphaned `.git/worktrees/<name>` admin entries at the parent
+        // root (this teardown's and any pre-existing prunable ones — GAIA-141).
+        if (this.options.root) {
+            await this.pruneWorktrees(this.options.root);
+        }
+        return true;
+    }
+    async startRun(input) {
+        const branchName = input.ticket.branchName;
+        const workspacePath = input.workspacePath;
+        const cfg = resolveStateConfig(this.options, input.ticket.state);
+        // 1. Already-open workspace for THIS worktree, keyed by the stable
+        //    identifier-derived PATH — never the branch (GAIA-114): the checked-out
+        //    branch is mutable (a coding agent may switch/rename it) and herdr
+        //    reports `null` for a detached HEAD, so a branch match is unreliable.
+        let workspaceId = await this.findOpenWorkspace(branchName, workspacePath);
+        // 2. Open workspace if not already open. Reattach from the PARENT repo
+        //    root, never the linked worktree path: herdr rejects an open whose
+        //    --cwd is a linked worktree with `linked_worktree_source` ("New and
+        //    open actions start from the repo parent workspace"), so passing
+        //    input.workspacePath (the linked path) makes every first dispatch of a
+        //    closed-on-disk worktree fail — the run is released and re-claimed in a
+        //    loop. Mirrors removeWorktree's reattach. Fall back to the linked path
+        //    only when no root is configured (rootless test callers).
+        if (!workspaceId) {
+            const openOutput = await this.execHerdr([
+                'worktree',
+                'open',
+                '--cwd',
+                this.options.root ?? workspacePath,
+                '--branch',
+                branchName,
+                '--no-focus',
+                '--json',
+            ]);
+            // Take the id from `open`'s OWN output — the reliable success path, with
+            // no branch match. Only if it carries none do we re-derive from the list
+            // (matched by the stable path, not the branch).
+            workspaceId = parseWorkspaceOpen(openOutput);
+            if (!workspaceId) {
+                const entries = await this.listWorktrees();
+                workspaceId =
+                    resolveWorktreeEntry(entries, branchName, workspacePath)
+                        ?.open_workspace_id ?? null;
+                if (!workspaceId) {
+                    // Surface the ACTUAL cause (AC #3): herdr's own open output and the
+                    // worktree state it listed — not just the generic per-branch message.
+                    throw new Error(`herdr worktree open did not yield a workspace id for path ${workspacePath} (branch ${branchName}). ` +
+                        `open output: ${openOutput.trim()}; listed worktrees: ${JSON.stringify(entries)}`);
+                }
+            }
+        }
+        const vars = {
+            identifier: input.ticket.identifier,
+            title: input.ticket.title,
+            titleSlug: slugify(input.ticket.title),
+            runUuid: input.run.uuid,
+            workspacePath: input.workspacePath,
+        };
+        // 3. Create tab — NO --json flag; label includes the run-id token
+        const { paneId: rootPaneId, tabId } = parseTabCreate(await this.execHerdr([
+            'tab',
+            'create',
+            '--workspace',
+            workspaceId,
+            '--label',
+            `${input.ticket.identifier} · ${input.ticket.state} #${input.run.id}`,
+            '--no-focus',
+        ]));
+        try {
+            // 4+5. Run the agent command in the root pane, then split each configured
+            // pane — the shared pane-layout primitive (same code path as the workspace
+            // open pane). The root command embeds `KEY='value'` env prefixes whose
+            // values may be secret (GAIA-99); pass a redactor so a failed pane-run
+            // exec-log carries key names, never values (only when env is present).
+            const hasEnv = Object.keys(input.env ?? {}).length > 0;
+            await applyPaneLayout(this.execHerdr, rootPaneId, { command: this.commandFor(input), panes: cfg.panes }, input.workspacePath, vars, hasEnv
+                ? { redactCommand: () => this.redactedCommandFor(input) }
+                : undefined);
+            // 6. Return branch as sessionRef (for logging)
+            return { sessionRef: branchName };
+        }
+        catch (err) {
+            // 7. Rollback: close only the just-created tab
+            await this.rollback(tabId);
+            throw err;
+        }
+    }
+    /** Best-effort cleanup: close only the just-created tab. Swallows errors. */
+    async rollback(tabId) {
+        try {
+            await this.execHerdr(['tab', 'close', tabId]);
+        }
+        catch {
+            // ignore — best-effort
+        }
+    }
+    /**
+     * No-op: at finalise time the agent is idle and its transcript is already on
+     * disk; the {@link cleanupRun} tab-close kills the PTY, so the agent dies
+     * implicitly. Kept to satisfy the run lifecycle seam.
+     */
+    async stopRun(_branch) { }
+    /**
+     * Close ONLY the branch-workspace tab whose label carries the `#<runId>`
+     * token (`herdr tab close <tab_id>`), killing that PTY (GAIA-183). The run
+     * identity lives in the tab label, so teardown is run-scoped: a sibling run's
+     * tab and any non-run tab in the same workspace are left untouched, and a
+     * missing match is a quiet no-op. Best-effort: a failing close is swallowed.
+     * No `/exit`/C-c and no `(done)` rename — the matched tab simply goes away.
+     * The branch worktree is untouched (that is the reap/{@link removeWorktree}
+     * lifecycle).
+     */
+    async cleanupRun(branch, runId) {
+        const workspaceId = await this.findWorkspaceByBranch(branch);
+        if (!workspaceId) {
+            return;
+        }
+        const tabs = parseTabList(await this.execHerdr(['tab', 'list', '--workspace', workspaceId]));
+        const match = tabs.find((tab) => labelMatchesRun(tab.label, runId));
+        if (!match) {
+            return; // no tab for this run — quiet best-effort no-op (AC-4)
+        }
+        try {
+            await this.execHerdr(['tab', 'close', match.tabId]);
+        }
+        catch {
+            // ignore — best-effort: a failing tab-close must not abort finalisation
+        }
+    }
+    commandFor(input) {
+        return this.assembleCommand(input, false);
+    }
+    /**
+     * The pane-run command with every env VALUE masked (key names kept). Used
+     * only for the exec log so a failed `pane run` never carries a secret DSN —
+     * consistent with the conductor's key-name-only env logging (GAIA-99).
+     */
+    redactedCommandFor(input) {
+        return this.assembleCommand(input, true);
+    }
+    assembleCommand(input, redact) {
+        const env = Object.entries(input.env ?? {}).map(([key, value]) => {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+                throw new Error(`invalid environment variable name for herdr: ${key}`);
+            }
+            return `${key}=${redact ? '<redacted>' : shellQuote(value)}`;
+        });
+        // herdr is agent-agnostic: it runs the command the conductor (via the agent
+        // plugin) provides, falling back to the configured default. No prompt build
+        // and no agent-specific flags here.
+        const command = input.command ?? this.options.command ?? 'claude';
+        return [...env, command].join(' ');
+    }
+}
+export function herdrExecutor(options = {}) {
+    return {
+        kind: 'executor',
+        id: 'herdr',
+        requiredModules: [],
+        async createExecutor(config, deps) {
+            // Derive the parent repo root via the single shared anchor (GAIA-177) so
+            // removeWorktree / worktree open reattach from the main clone, not the
+            // linked worktree — identical derivation to the sibling herdrWorkspace.
+            const root = await deriveHerdrRoot(config.config_path, {
+                ...(options.root !== undefined ? { override: options.root } : {}),
+                ...(options.execGit ? { execGit: options.execGit } : {}),
+            });
+            // Lifecycle hooks are top-level config (GAIA-84); the executor runs them
+            // best-effort through its injected logger.
+            return new HerdrExecutor({
+                command: options.command ?? 'claude',
+                root,
+                ...(options.hooks ? { hooks: options.hooks } : {}),
+                ...(config.hooks ? { hooks: config.hooks } : {}),
+                ...(options.default ? { default: options.default } : {}),
+                ...(options.states ? { states: options.states } : {}),
+            }, defaultExec, deps.logger);
+        },
+    };
+}
+// Default export: this module also exports the `HerdrExecutor` class, so the
+// config resolver's auto-pick (no `export:`) sees 2 function exports and
+// would otherwise throw "specify export" — see conductor/src/config.ts
+// `loadNamedPlugin`. The default export makes the factory win.
+export default herdrExecutor;