@gaia-ai/addon-herdr 0.6.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 keytec GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,5 @@
+# @gaia-ai/addon-herdr
+
+GAIA herdr integration: spawn executor + per-ticket worktree workspace.
+
+Part of the GAIA CLI. Install the meta package `@gaia-ai/gaia` to get the `gaia` CLI with all addons. Source: https://git.key-tec.de/keytec/gaia (gaia-cli/).

package/dist/src/agent-host.d.ts

@@ -0,0 +1,45 @@
+/** A hosted agent as reported by the host. `id` is the host-owned stable handle
+ *  (survives a TUI restart); `group` is the opaque grouping key it was launched
+ *  under; `label` is a human tag for the list. */
+export interface HostedAgent {
+    id: string;
+    group: string;
+    label: string;
+}
+/**
+ * The INTENT-level agent host herdr provides. The caller says "launch an agent
+ * in this group", "show that agent", "list this group" — it never names panes,
+ * tabs, splits or zoom. The host (herdr) owns the whole layout policy. `group`
+ * is OPAQUE (gaia passes the project slug). `command` is the resolved shell
+ * command the agent runs (the renderer's prompt is turned into a command by the
+ * `gaia ui` entry before it reaches here — herdr stays agent-binary-agnostic).
+ */
+export interface AgentLaunchHost {
+    /**
+     * Start an agent and return its stable handle. The host decides where the
+     * session is placed and shows it; the caller only supplies intent + a group.
+     */
+    launch(opts: {
+        group: string;
+        cwd: string;
+        command: string;
+        env?: Record<string, string | undefined> | undefined;
+        label?: string | undefined;
+    }): Promise<HostedAgent>;
+    /** The live agents of a group — the source of truth for the list, rebuilt
+     *  from the host on demand so sessions survive a TUI restart. */
+    list(group: string): Promise<HostedAgent[]>;
+    /** Bring one agent to the foreground (the host zooms/switches as it sees fit). */
+    focus(id: string): Promise<void>;
+    /** Stop showing a group's agents and return focus to the caller. Durable —
+     *  the agents keep running; this never terminates them. */
+    hide(group: string): Promise<void>;
+    /** Terminate one agent for good. */
+    kill(id: string): Promise<void>;
+    /** Send literal text to an agent's input. */
+    sendText(id: string, text: string): Promise<void>;
+}
+/** A workspace (or other plugin) that can host agents at the intent level. */
+export interface AgentLaunchHostProvider {
+    agentHost: AgentLaunchHost;
+}

package/dist/src/agent-host.js

@@ -0,0 +1,9 @@
+// Herdr's own agent-host contract (GAIA-194 AC-3). It used to live in
+// `@gaia-ai/core` as `AgentLaunchHost`/`HostedAgent`, but the agent-host seam is
+// a TUI/renderer concern, not a conductor-engine one — so core dropped it and
+// herdr types its impl LOCALLY. This interface imports nothing removed and
+// nothing from `@gaia-ai/addon-gaia-ui`: the renderer owns its own
+// prompt-level `TuiAgentService`, and the conductor `gaia ui` entry adapts this
+// mechanism-level (`command`-based) host to it. Structurally compatible, no
+// cross-package type coupling.
+export {};

package/dist/src/agents.d.ts

@@ -0,0 +1,3 @@
+import type { AgentLaunchHost } from './agent-host.js';
+import type { HerdrExec } from './pane-layout.js';
+export declare function herdrAgentHost(execHerdr: HerdrExec): AgentLaunchHost;

package/dist/src/agents.js

@@ -0,0 +1,111 @@
+import { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
+/** The single tab that holds a group's agent panes. */
+const groupTabLabel = (group) => `gaia-agents:${group}`;
+export function herdrAgentHost(execHerdr) {
+    // The caller's home tab, returned to on hide. Captured lazily on the first
+    // launch — that is when the caller is focused on its own tab (pressing `n`),
+    // and it keeps construction side-effect-free. Best-effort: a probe failure
+    // just leaves hide without a home to return to.
+    let homeTab = null;
+    const captureHome = async () => {
+        if (homeTab !== null)
+            return;
+        try {
+            homeTab = parsePaneInfo(await execHerdr(['pane', 'current'])).tabId;
+        }
+        catch {
+            // no home tab known; hide() becomes a no-op focus
+        }
+    };
+    // Cache each group's tab id to skip the `tab list` round-trip once known.
+    const tabByGroup = new Map();
+    const resolveTab = async (group) => {
+        const cached = tabByGroup.get(group);
+        if (cached)
+            return cached;
+        const found = findTabIdByLabel(await execHerdr(['tab', 'list']), groupTabLabel(group));
+        if (found)
+            tabByGroup.set(group, found);
+        return found;
+    };
+    return {
+        async launch({ group, cwd, command, env, label }) {
+            await captureHome();
+            const e = env ?? {};
+            // Find the group's tab and split off a LIVE pane (newest-first; a stale
+            // pane — a previous agent died/was closed — is skipped). None survive, or
+            // no tab yet → create the group tab (its root pane is the agent).
+            let pane = null;
+            const tabId = await resolveTab(group);
+            if (tabId) {
+                const panes = parsePanesInTab(await execHerdr(['pane', 'list']), tabId);
+                for (const p of [...panes].reverse()) {
+                    try {
+                        pane = parsePaneInfo(await execHerdr([
+                            'pane',
+                            'split',
+                            p.paneId,
+                            '--direction',
+                            'right',
+                            '--no-focus',
+                            '--cwd',
+                            cwd,
+                            ...envArgs(e),
+                        ]));
+                        break;
+                    }
+                    catch {
+                        // stale pane — try the next
+                    }
+                }
+                if (!pane)
+                    tabByGroup.delete(group);
+            }
+            if (!pane) {
+                pane = parseTabCreate(await execHerdr([
+                    'tab',
+                    'create',
+                    '--cwd',
+                    cwd,
+                    '--no-focus',
+                    '--label',
+                    groupTabLabel(group),
+                    ...envArgs(e),
+                ]));
+                tabByGroup.set(group, pane.tabId);
+            }
+            await execHerdr(['pane', 'run', pane.paneId, command]);
+            const human = label ?? 'agent';
+            await execHerdr(['pane', 'rename', pane.paneId, human]).catch(() => { });
+            await execHerdr(['pane', 'zoom', pane.paneId, '--on']).catch(() => { });
+            return { id: pane.paneId, group, label: human };
+        },
+        async list(group) {
+            const tabId = await resolveTab(group);
+            if (!tabId)
+                return [];
+            return parsePanesInTab(await execHerdr(['pane', 'list']), tabId).map((p) => ({ id: p.paneId, group, label: p.label }));
+        },
+        async focus(id) {
+            await execHerdr(['pane', 'zoom', id, '--on']);
+        },
+        async hide(group) {
+            // Un-zoom the group's panes (so it reads as the tiled overview next time)
+            // and return focus to the caller's home tab. The agents keep running.
+            const tabId = await resolveTab(group);
+            if (tabId) {
+                for (const p of parsePanesInTab(await execHerdr(['pane', 'list']), tabId)) {
+                    await execHerdr(['pane', 'zoom', p.paneId, '--off']).catch(() => { });
+                }
+            }
+            if (homeTab)
+                await execHerdr(['tab', 'focus', homeTab]).catch(() => { });
+        },
+        async kill(id) {
+            await execHerdr(['pane', 'close', id]);
+        },
+        async sendText(id, text) {
+            await execHerdr(['pane', 'send-text', id, text]);
+        },
+    };
+}

package/dist/src/config.d.ts

@@ -0,0 +1,55 @@
+import type { RootGitExec } from './root-anchor.js';
+export interface PaneSpec {
+    direction: 'right' | 'down';
+    command: string;
+    focus?: boolean;
+}
+export interface StateConfig {
+    /**
+     * Tab label template. Must contain {identifier} — the conductor matches a
+     * run's tab by its ticket identifier (stop/state), so the identifier is the
+     * stable anchor in the visible name. Other vars: {title}, {titleSlug},
+     * {runUuid}, {repoName}, {workspacePath}.
+     */
+    tabLabel?: string;
+    workspaceLabel?: string;
+    /** Extra layout panes (diff/logs); NOT the agent command. */
+    panes?: PaneSpec[];
+}
+export interface HerdrExecutorOptions {
+    /** Legacy fallback for input.command. */
+    command?: string;
+    /**
+     * Lifecycle-hook commands, keyed like `config.hooks` (after_create,
+     * before_run, after_run, after_done). The factory copies `config.hooks` here
+     * so the executor — the single best-effort catch point — can run them.
+     */
+    hooks?: {
+        after_create?: string;
+        before_run?: string;
+        after_run?: string;
+        after_done?: string;
+    };
+    /**
+     * The parent repo root (main clone) — herdr `--cwd` target for reattaching a
+     * closed worktree. herdr rejects a `worktree open` whose --cwd is a linked
+     * worktree (`linked_worktree_source`): open/new must start from the parent
+     * workspace. When unset the factory derives it from the git common dir
+     * (GAIA-177), exactly like the sibling `herdrWorkspace` plugin; this override
+     * always wins.
+     */
+    root?: string;
+    /** Overrideable git exec for root derivation (tests). */
+    execGit?: RootGitExec;
+    default?: StateConfig;
+    states?: Record<string, StateConfig>;
+}
+export interface ResolvedConfig {
+    tabLabel: string;
+    workspaceLabel: string;
+    panes: PaneSpec[];
+}
+export declare const BUILTIN_DEFAULTS: ResolvedConfig;
+export declare function resolveStateConfig(options: HerdrExecutorOptions, state: string): ResolvedConfig;
+export declare function renderTemplate(tpl: string, vars: Record<string, string>): string;
+export declare function assertTabLabelTemplate(tabLabel: string): void;

package/dist/src/config.js

@@ -0,0 +1,27 @@
+export const BUILTIN_DEFAULTS = {
+    tabLabel: '{identifier} · {titleSlug}',
+    workspaceLabel: '{repoName}',
+    panes: [],
+};
+export function resolveStateConfig(options, state) {
+    const base = options.default ?? {};
+    const stateCfg = options.states?.[state] ?? {};
+    return {
+        tabLabel: stateCfg.tabLabel ?? base.tabLabel ?? BUILTIN_DEFAULTS.tabLabel,
+        workspaceLabel: stateCfg.workspaceLabel ??
+            base.workspaceLabel ??
+            BUILTIN_DEFAULTS.workspaceLabel,
+        panes: stateCfg.panes ?? base.panes ?? BUILTIN_DEFAULTS.panes,
+    };
+}
+export function renderTemplate(tpl, vars) {
+    return tpl.replace(/\{(\w+)\}/g, (whole, key) => {
+        const value = vars[key];
+        return value === undefined ? whole : value;
+    });
+}
+export function assertTabLabelTemplate(tabLabel) {
+    if (!tabLabel.includes('{identifier}')) {
+        throw new Error(`herdr tabLabel must contain {identifier} for stop/state matching: ${tabLabel}`);
+    }
+}

package/dist/src/fs.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Recursively re-add the owner-write bit to a directory tree.
+ *
+ * A GAIA worktree is a Drupal install, and Drupal hardens `web/sites/default`
+ * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
+ * without its write bit cannot have its entries unlinked, so removing the
+ * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
+ * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
+ * succeed — this is not an ownership problem, only the permission bits.
+ *
+ * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
+ * owner) must not abort the walk. Symlinks are never followed — chmod would
+ * touch the link target, which may live outside the tree.
+ */
+export declare function restoreWritable(path: string): void;
+/**
+ * Remove a directory tree that may be hardened read-only by Drupal:
+ * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
+ * the unlink; when herdr performs the removal, call {@link restoreWritable}
+ * alone beforehand. A missing path is a no-op.
+ */
+export declare function forceRemoveDir(path: string): void;

package/dist/src/fs.js

@@ -0,0 +1,58 @@
+import { chmodSync, lstatSync, readdirSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Recursively re-add the owner-write bit to a directory tree.
+ *
+ * A GAIA worktree is a Drupal install, and Drupal hardens `web/sites/default`
+ * to `0555` and `settings.php` / `files/.htaccess` to `0444`. A directory
+ * without its write bit cannot have its entries unlinked, so removing the
+ * worktree (`git worktree remove --force` / `rm -rf`, however herdr does it)
+ * gets EACCES. Restoring `u+w` on every dir/file first is what makes removal
+ * succeed — this is not an ownership problem, only the permission bits.
+ *
+ * Best-effort per entry: a single un-chmod-able entry (already gone, foreign
+ * owner) must not abort the walk. Symlinks are never followed — chmod would
+ * touch the link target, which may live outside the tree.
+ */
+export function restoreWritable(path) {
+    let stat;
+    try {
+        stat = lstatSync(path);
+    }
+    catch {
+        return; // gone / inaccessible — nothing to restore
+    }
+    if (stat.isSymbolicLink()) {
+        return; // don't follow: the target lives elsewhere
+    }
+    try {
+        // Add owner-write, preserving every other bit (read/execute stay intact so
+        // a directory remains traversable and readable for the recursion below).
+        chmodSync(path, stat.mode | 0o200);
+    }
+    catch {
+        // best-effort: one un-chmod-able entry must not abort the walk
+    }
+    if (stat.isDirectory()) {
+        let entries;
+        try {
+            entries = readdirSync(path);
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            restoreWritable(join(path, entry));
+        }
+    }
+}
+/**
+ * Remove a directory tree that may be hardened read-only by Drupal:
+ * {@link restoreWritable} first, then `rm -rf`. Used where the conductor owns
+ * the unlink; when herdr performs the removal, call {@link restoreWritable}
+ * alone beforehand. A missing path is a no-op.
+ */
+export function forceRemoveDir(path) {
+    restoreWritable(path);
+    rmSync(path, { recursive: true, force: true });
+}

package/dist/src/index.d.ts

@@ -0,0 +1,172 @@
+import type { ExecutorCapabilities, ExecutorPlugin, GaiaExecutor, HookContext, HookName, SpawnedSession, SpawnRunInput } from '@gaia-ai/conductor/contract';
+import type { ConductorLogger } from '@gaia-ai/core';
+import { type HerdrExecutorOptions } from './config.js';
+import { type HerdrExec } from './pane-layout.js';
+export type { AgentLaunchHost, AgentLaunchHostProvider, HostedAgent, } from './agent-host.js';
+export { herdrAgentHost } from './agents.js';
+export type { HerdrExec } from './pane-layout.js';
+export { envArgs, findTabIdByLabel, parsePaneInfo, parsePanesInTab, parseTabCreate, } from './panes.js';
+export { HerdrWorkspace, type HerdrWorkspaceOptions, herdrWorkspace, type OpenLayout, } from './workspace.js';
+/** Runs a lifecycle-hook shell command in a cwd; rejects on non-zero exit. */
+export type ShellRunner = (command: string, cwd: string, env?: Record<string, string>) => Promise<void>;
+/** Runs `git <args>` in a cwd; resolves with stdout, rejects on non-zero exit. */
+export type GitRunner = (args: string[], cwd: string) => Promise<string>;
+export declare class HerdrExecutor implements GaiaExecutor {
+    private readonly options;
+    private readonly execHerdr;
+    private readonly logger;
+    private readonly runShell;
+    private readonly runGit;
+    readonly id = "herdr";
+    constructor(options: HerdrExecutorOptions, execHerdr?: HerdrExec, logger?: ConductorLogger, runShell?: ShellRunner, runGit?: GitRunner);
+    capabilities(): ExecutorCapabilities;
+    /**
+     * 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.
+     */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<void>;
+    /**
+     * 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.
+     */
+    private listWorktrees;
+    /**
+     * Find the worktree entry (path + open_workspace_id) for a branch via
+     * worktree list. Returns null if the branch has no worktree.
+     */
+    private findWorktreeByBranch;
+    /**
+     * Find the open_workspace_id for a branch via worktree list.
+     * Returns null if no workspace is open for that branch.
+     */
+    private findWorkspaceByBranch;
+    /**
+     * 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.
+     */
+    private findOpenWorkspace;
+    /** Parent repo root for git worktree admin ops (falls back to `fallback`). */
+    private gitRoot;
+    /**
+     * 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.
+     */
+    private pruneWorktrees;
+    /**
+     * 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.
+     */
+    private gitAwareRemove;
+    /**
+     * 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.
+     */
+    private findGitWorktree;
+    /**
+     * 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.
+     */
+    private ensureFocusSafeToRemove;
+    /**
+     * 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).
+     */
+    removeWorktree(branch: string, worktreePath?: string): Promise<boolean>;
+    startRun(input: SpawnRunInput): Promise<SpawnedSession>;
+    /** Best-effort cleanup: close only the just-created tab. Swallows errors. */
+    private rollback;
+    /**
+     * 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.
+     */
+    stopRun(_branch: string): Promise<void>;
+    /**
+     * 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).
+     */
+    cleanupRun(branch: string, runId: number): Promise<void>;
+    private commandFor;
+    /**
+     * 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).
+     */
+    private redactedCommandFor;
+    private assembleCommand;
+}
+export declare function herdrExecutor(options?: HerdrExecutorOptions): ExecutorPlugin;
+export default herdrExecutor;