/**
 * `Workspace` — git-worktree isolation for teammates.
 *
 * Each teammate agent in the swarm needs its own checkout to mutate without
 * trampling its peers: its own working tree, its own branch, its own index.
 * Git's native answer is a *worktree* — a second working directory linked to
 * one shared object store. `Workspace` is the thin class that provisions and
 * reclaims those worktrees on the swarm's behalf.
 *
 * It deliberately owns no `node:child_process` of its own. Every git
 * invocation flows through an injected {@link ShellRunner} (see
 * {@link import("./runner").ShellRunner}); the default is the real
 * {@link nodeRunner}, and tests pass a scripted fake that asserts on the exact
 * git command and returns canned output. This is what makes worktree
 * provisioning unit-testable without a repo on disk.
 *
 * Three verbs:
 *   - {@link Workspace.create} runs `git worktree add` to materialize a fresh
 *     working tree on a named branch and reports back its path and branch.
 *   - {@link Workspace.list} parses `git worktree list --porcelain` into a
 *     structured inventory of every worktree git knows about.
 *   - {@link Workspace.remove} runs `git worktree remove` then prunes stale
 *     administrative metadata, so a reclaimed slot leaves nothing behind.
 *
 * Every git failure — a non-zero exit, or the runner being unable to spawn git
 * at all — is mapped onto a single typed {@link SwarmFault} of kind
 * `isolation`, with the failing command and git's own stderr preserved in the
 * message and the underlying error threaded onto `cause`. Callers branch on
 * `SwarmFault.is(err, "isolation")` rather than scraping git's text.
 */
import type { ShellRunner } from "./runner";
/** The coordinates of a provisioned worktree. */
export interface WorktreeRef {
    /** Absolute (or git-reported) path of the linked working directory. */
    readonly path: string;
    /**
     * The branch checked out in that working directory, as a short ref name
     * (e.g. `feature/login`, not `refs/heads/feature/login`). May be `null` for a
     * detached-HEAD worktree surfaced by {@link Workspace.list}.
     */
    readonly branch: string | null;
}
/** One entry parsed from `git worktree list --porcelain`. */
export interface WorktreeEntry extends WorktreeRef {
    /** The commit the worktree's HEAD points at, when git reported one. */
    readonly head: string | null;
    /** True when the worktree is in detached-HEAD state (no branch). */
    readonly detached: boolean;
    /** True when git flagged the worktree as bare. */
    readonly bare: boolean;
    /** True when git flagged the worktree as locked. */
    readonly locked: boolean;
}
/** Options accepted by {@link Workspace.create}. */
export interface CreateOptions {
    /**
     * Where to place the new working directory. When omitted, the worktree is
     * created at a sibling path git derives from the branch name; supply this to
     * control placement (the usual case for per-teammate scratch dirs).
     */
    readonly path?: string;
    /**
     * The committish the new branch starts from (a branch, tag, or SHA). When
     * omitted, git branches from the base repo's current `HEAD`.
     */
    readonly startPoint?: string;
}
/** Options accepted by {@link Workspace.remove}. */
export interface RemoveOptions {
    /**
     * Pass `--force` to `git worktree remove`, letting git reclaim a worktree
     * that still has uncommitted changes or a locked administrative file. Off by
     * default so an accidental remove of dirty work is refused.
     */
    readonly force?: boolean;
}
/**
 * Provisions and reclaims git worktrees through an injected shell runner.
 *
 * Construct directly; the runner defaults to {@link nodeRunner} so callers that
 * just want real git can write `new Workspace()`. Pass a fake runner to drive
 * the class in tests.
 */
export declare class Workspace {
    private readonly runner;
    /**
     * @param runner The shell seam every git command is sent through. Defaults to
     *   the production {@link nodeRunner}; inject a fake in tests.
     */
    constructor(runner?: ShellRunner);
    /**
     * Materialize a fresh worktree on a new branch.
     *
     * Runs `git worktree add [-b <branch>] <path> [<start-point>]` inside
     * `baseRepo`. The branch is created (git's `-b`), so `branch` must not
     * already exist as a worktree-checked-out ref. Returns the worktree's
     * resolved path and branch on success; a non-zero exit (e.g. the branch
     * already exists, the path is occupied) raises an `isolation` fault.
     *
     * @param baseRepo Directory of the repository the worktree links into.
     * @param branch   Short name of the branch to create and check out.
     * @param opts     Optional placement and start-point overrides.
     */
    create(baseRepo: string, branch: string, opts?: CreateOptions): Promise<WorktreeRef>;
    /**
     * Enumerate every worktree git tracks for `baseRepo`.
     *
     * Runs `git worktree list --porcelain` and parses the stable, machine-facing
     * porcelain format into {@link WorktreeEntry} records (the first record is the
     * main working tree; the rest are linked worktrees). A non-zero exit raises an
     * `isolation` fault.
     *
     * @param baseRepo Directory of the repository to inventory.
     */
    list(baseRepo: string): Promise<WorktreeEntry[]>;
    /**
     * Remove a linked worktree and prune its leftover metadata.
     *
     * Runs `git worktree remove <path>` (with `--force` when
     * `opts.force`) and then `git worktree prune`, so a removed worktree leaves no
     * dangling administrative entry under `.git/worktrees`. Either step failing
     * raises an `isolation` fault; the prune runs from the base repo so it can be
     * invoked even after the worktree directory itself is gone.
     *
     * @param path     The worktree working directory to remove.
     * @param baseRepo Directory of the owning repository the prune runs in. When
     *   omitted, both commands run from the worktree `path` (sufficient while the
     *   worktree still exists; pass `baseRepo` to prune after manual deletion).
     */
    remove(path: string, baseRepo?: string, opts?: RemoveOptions): Promise<void>;
    /**
     * Run one git command through the injected runner and assert success.
     *
     * Resolves with the {@link RunResult} on a zero exit. A non-zero exit, or the
     * runner rejecting outright (git not spawnable), is folded into one
     * `isolation` fault carrying the command, git's stderr, and the original
     * trigger on `cause`.
     */
    private git;
    /** Derive a default sibling worktree path from the branch name. */
    private defaultPath;
}
