@bakers-build/addon-herdr 0.0.0-stage → 0.1.0-next.38

package/dist/src/index.d.ts

@@ -0,0 +1,219 @@
+import type { BbExecutor, ExecutorCapabilities, ExecutorPlugin, HookContext, HookName, HookResult, SpawnedSession, SpawnRunInput, WorktreeTeardown } from '@bakers-build/conductor/contract';
+import type { ConductorLogger } from '@bakers-build/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 { herdrProcessHost } from './process-host.js';
+export { HerdrWorkspace, type HerdrWorkspaceOptions, herdrWorkspace, type OpenLayout, } from './workspace.js';
+export { parseWorkspaceList, type WorkspaceEntry, } from './workspace-list.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 BbExecutor {
+    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 BbExecutor.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.
+     *
+     * BB-237: it also RETURNS what happened ({@link HookResult}). Not throwing
+     * kept a hook from wedging a run, but swallowing the outcome entirely left the
+     * caller unable to tell a provisioned worktree from a broken one — so an agent
+     * was dispatched into a worktree whose bootstrap had aborted, with nothing but
+     * a log line (which, on a TTY, went nowhere) to say so.
+     */
+    runHook(name: HookName, cwd: string, ctx: HookContext, env?: Record<string, string>): Promise<HookResult>;
+    /**
+     * List worktrees, ALWAYS anchored to the configured parent repo root
+     * (BB-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
+     * `bakers-cleanup-*` integration test selected then deleted a
+     * `/tmp/bakers-cleanup-*` repo, that stale context survives and the unanchored
+     * list exits (`cannot change to '/tmp/bakers-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 BB-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 (BB-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 (BB-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 —
+     *      but ONLY when the path really is a registered worktree (BB-293):
+     *      against an unregistered path git exits 128 and the shared exec helper
+     *      logs `ERROR: exec failed` for a condition this code expects and
+     *      handles. The guard lives here rather than at the caller because this
+     *      method has a second call site (the path resolved via
+     *      {@link findGitWorktree});
+     *   3. guarantees the directory is gone (a raw force-remove) in case git
+     *      refused or was skipped — a no-op if git already removed it;
+     *   4. prunes the repo so any now-stale admin entry is swept.
+     *
+     * Returns whether the directory is gone afterwards. A reclaim that cannot
+     * remove it REPORTS instead of throwing (BB-293, spec D5): the raw EACCES
+     * used to propagate all the way out of {@link removeWorktree} and reach the
+     * reaper as an opaque exception.
+     */
+    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 (BB-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. Returns null when nothing matches. Best-effort: a
+     * git failure resolves to null.
+     *
+     * `cwd` is only where git is RUN. The main worktree is excluded by git's own
+     * porcelain ordering (it is always the first record) rather than by comparing
+     * against `cwd`, because the two coincide only when a parent root is
+     * configured. Without one the probe falls back to running git inside the
+     * worktree itself, and a `path !== cwd` filter then dropped the very entry
+     * being asked about — so `registered: true` was unreachable for a rootless
+     * executor (BB-293 review, finding 1). The configured root is excluded too,
+     * belt and braces, so a caller that anchors elsewhere still never resolves the
+     * main checkout as a ticket worktree.
+     */
+    private findGitWorktree;
+    /**
+     * Ask — passively — whether this worktree still exists, in BOTH dimensions
+     * that can come apart (BB-293): git's registration, and the directory on
+     * disk. The reported failure was exactly a case where they disagreed — the
+     * directory was there, the registration was not — so a single-dimension
+     * check cannot decide what to do.
+     *
+     * Passive by construction: it writes nothing, calls no herdr, and NEVER
+     * throws. A git failure yields `registered: false`, degrading the verdict to
+     * the on-disk answer rather than failing the teardown.
+     *
+     * The persisted `worktreePath` is the stable key and wins when given;
+     * `registered` then describes THAT path, never a branch match pointing
+     * somewhere else (the checked-out branch is mutable — BB-114).
+     *
+     * git is run at the configured parent root when there is one, else inside the
+     * worktree itself — `git worktree list` enumerates the whole repo from any of
+     * its worktrees, so the rootless answer is the same list.
+     */
+    private probeWorktree;
+    /**
+     * BB-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
+     * (BB-141 RC-1). Since BB-293 that resolution starts by ASKING — a passive
+     * {@link probeWorktree} reads both dimensions of existence and the four cases
+     * branch explicitly:
+     *   - neither registered nor on disk → nothing to do at all;
+     *   - registered but gone from disk → sweep the prunable admin entry;
+     *   - on disk but not registered → reclaim the directory, WITHOUT asking git
+     *     to remove a worktree it does not know (the bogus `ERROR: exec failed`);
+     *   - both → reclaim it git-awarely, `git worktree remove` included.
+     * A path that resolves in NEITHER dimension is not "absent" — it is
+     * unresolved, and still reported `unverified` (BB-141 RC-2).
+     *
+     * Reports what the teardown DID (BB-293): `removed` when the worktree is
+     * gone because this host removed it (or reclaimed an on-disk orphan, or swept
+     * the prunable admin entry it left behind), `already_absent` when a RESOLVED
+     * worktree existed in neither dimension, and `unverified` ONLY when nothing
+     * was resolvable or the directory could not be reclaimed — the reaper then
+     * leaves the ticket on its work list for a later retry instead of falsely
+     * flagging it cleaned (BB-141 RC-2).
+     */
+    removeWorktree(branch: string, worktreePath?: string): Promise<WorktreeTeardown>;
+    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 (BB-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;
+}
+export declare function herdrExecutor(options?: HerdrExecutorOptions): ExecutorPlugin;
+export default herdrExecutor;