indusagi 0.12.32 → 0.12.33

package/dist/types/smithy/ui/transcript.d.ts

@@ -0,0 +1,183 @@
+/**
+ * `TranscriptModel` — a visitor over a build-conversation transcript.
+ *
+ * Smithy's agent-building session is, underneath, an ordinary model conversation:
+ * an ordered list of {@link Turn}s, each a bag of typed {@link Block}s. Before any
+ * of that can be shown to a person — or written to a session log — it has to be
+ * *cleaned* and *projected*: secrets stripped, runaway whitespace collapsed, giant
+ * blobs (a pasted file, a base64 image) redacted to a short placeholder, and the
+ * whole thing reshaped from the gateway's wire vocabulary into a small, flat,
+ * render-friendly form. The original sanitizers did this as a scatter of
+ * `normalize*` helpers; this module folds them into a single disciplined visitor.
+ *
+ * The visitor is *table-driven*. {@link TranscriptModel} holds one
+ * {@link BlockVisitor} per block kind; walking a turn is a `switch`-free dispatch
+ * through that table, so adding a new block kind is adding one table entry, never
+ * editing a ladder. Each visitor is a pure function `(block, ctx) => RenderBlock |
+ * null`; returning `null` drops the block (e.g. an empty text fragment that
+ * collapsed to nothing). The sanitizers themselves are likewise pure string
+ * transforms composed in a fixed order, so the projection is deterministic and
+ * trivially testable.
+ *
+ * `accept(turns)` is the one public entry point: it walks every turn, runs each
+ * block through its visitor, and returns a {@link RenderTranscript}. Nothing here
+ * touches a terminal — rendering lives behind the {@link ForgeView} text seam.
+ */
+import type { Block, CommandBlock, ImageBlock, TextBlock, ThinkingBlock, ToolCallBlock, ToolResultBlock, Turn } from "../../llmgateway/contract";
+/** The kind of every block in a projected transcript (mirrors {@link Block}). */
+export type RenderBlockKind = "text" | "thinking" | "tool_call" | "tool_result" | "image" | "command";
+/** A speaker label, derived from a {@link Turn}'s role. */
+export type RenderRole = "user" | "assistant" | "tool";
+/**
+ * One sanitized, flattened content fragment ready to render.
+ *
+ * Every block kind collapses to this single shape: a `kind` tag, a one-line
+ * `label` naming the fragment for a viewer, and the cleaned `text` to show. The
+ * optional `redacted` flag marks fragments whose body was replaced by a
+ * placeholder (a long blob, binary media, a secret), so a renderer can style
+ * them differently.
+ */
+export interface RenderBlock {
+    /** Which block kind this projection came from. */
+    readonly kind: RenderBlockKind;
+    /** A short, human-readable label (e.g. `tool · read_file`). */
+    readonly label: string;
+    /** The sanitized, render-ready body text. */
+    readonly text: string;
+    /** True when {@link text} is a placeholder standing in for omitted content. */
+    readonly redacted?: boolean;
+}
+/** A single projected turn: a speaker plus its surviving render blocks. */
+export interface RenderTurn {
+    /** The speaker, projected from the source turn's role. */
+    readonly role: RenderRole;
+    /** The sanitized blocks, in source order, with dropped blocks removed. */
+    readonly blocks: readonly RenderBlock[];
+}
+/** The full result of {@link TranscriptModel.accept}: a render-ready transcript. */
+export interface RenderTranscript {
+    /** Every projected turn, in source order. */
+    readonly turns: readonly RenderTurn[];
+    /** Count of fragments whose body was redacted across the whole transcript. */
+    readonly redactionCount: number;
+}
+/**
+ * Tunable thresholds for the sanitizing passes.
+ *
+ * Defaults are deliberately conservative: collapse whitespace always, redact any
+ * single fragment longer than {@link maxLength} characters, and replace anything
+ * that matches a secret pattern. A caller can widen or tighten these per session.
+ */
+export interface SanitizeOptions {
+    /** Bodies longer than this (in characters) are redacted to a placeholder. */
+    readonly maxLength: number;
+    /** Extra regexes whose matches are masked, on top of the built-in set. */
+    readonly secretPatterns: readonly RegExp[];
+}
+/** The default sanitizing thresholds used when a caller passes none. */
+export declare const DEFAULT_SANITIZE_OPTIONS: SanitizeOptions;
+/** The per-block context a visitor receives alongside the block it projects. */
+export interface VisitContext {
+    /** The sanitizing thresholds in force for this walk. */
+    readonly options: SanitizeOptions;
+    /** The role of the turn the block belongs to. */
+    readonly role: RenderRole;
+}
+/**
+ * A visitor for one block kind: a pure projection from a typed block to a
+ * {@link RenderBlock}, or `null` to drop the block from the output.
+ */
+export type BlockVisitor<B extends Block> = (block: B, ctx: VisitContext) => RenderBlock | null;
+/** The complete dispatch table: one visitor keyed by each {@link Block} kind. */
+export interface VisitorTable {
+    readonly text: BlockVisitor<TextBlock>;
+    readonly thinking: BlockVisitor<ThinkingBlock>;
+    readonly tool_call: BlockVisitor<ToolCallBlock>;
+    readonly tool_result: BlockVisitor<ToolResultBlock>;
+    readonly image: BlockVisitor<ImageBlock>;
+    readonly command: BlockVisitor<CommandBlock>;
+}
+/**
+ * The default visitor table — the projection rules the original `normalize*`
+ * helpers encoded, gathered into one place.
+ *
+ * Each entry sanitizes the block's salient text, attaches a descriptive label,
+ * and returns a {@link RenderBlock}. Text fragments that collapse to nothing are
+ * dropped (`null`); images never carry their bytes into the projection (the
+ * base64 payload is always redacted to a one-line descriptor).
+ */
+export declare const DEFAULT_VISITORS: VisitorTable;
+/**
+ * A visitor over a build-conversation transcript.
+ *
+ * Construct one with optional sanitize {@link SanitizeOptions} and an optional
+ * override {@link VisitorTable}, then call {@link accept} with a turn list to get
+ * back a sanitized, render-ready {@link RenderTranscript}. The model is stateless
+ * between calls — every `accept` is independent — so a single instance can be
+ * reused across as many transcripts as a session produces.
+ */
+export declare class TranscriptModel {
+    private readonly options;
+    private readonly visitors;
+    constructor(options?: Partial<SanitizeOptions>, visitors?: Partial<VisitorTable>);
+    /**
+     * Walk `turns`, sanitize and project every block, and return the result.
+     *
+     * Turns are visited in order; within each turn, blocks are dispatched through
+     * the visitor table by kind. A visitor returning `null` drops its block. A turn
+     * is kept even when all its blocks drop (an empty {@link RenderTurn}) so the
+     * speaker sequence is preserved for the renderer.
+     */
+    accept(turns: readonly Turn[]): RenderTranscript;
+    /**
+     * Dispatch one block to its visitor.
+     *
+     * The `block.kind` tag narrows the union, and the matching table entry — typed
+     * to that exact variant — does the projection. There is no `switch`: the table
+     * *is* the dispatch.
+     */
+    private visit;
+}
+/**
+ * The minimal text seam Smithy renders through.
+ *
+ * Deliberately tiny — two methods — and free of any terminal toolkit, so the
+ * builder loop can `show` lines of a projected transcript and `ask` the user for
+ * their next instruction without ever importing Ink or coupling to a UI. A richer
+ * view (a TUI, a web pane) is slotted in later by implementing this interface.
+ */
+export interface ForgeView {
+    /** Present one already-formatted line to the user. */
+    show(line: string): void;
+    /** Prompt the user with `question` and resolve their typed answer. */
+    ask(question: string): Promise<string>;
+}
+/**
+ * The default {@link ForgeView}: stdout for output, a readline prompt for input.
+ *
+ * It writes each shown line straight to the output stream (a trailing newline is
+ * added) and reads a single line of input per `ask` via Node's `readline`. The
+ * readline interface is created lazily on the first `ask` and closed by
+ * {@link close}, so a view that only ever `show`s never opens an input handle.
+ */
+export declare class ConsoleForgeView implements ForgeView {
+    private readonly output;
+    private readonly input;
+    private rl;
+    constructor(output?: NodeJS.WritableStream, input?: NodeJS.ReadableStream);
+    show(line: string): void;
+    ask(question: string): Promise<string>;
+    /** Close the underlying readline interface, if one was ever opened. */
+    close(): void;
+    /** Open the readline interface on first use; reuse it thereafter. */
+    private ensureReadline;
+}
+/**
+ * Format a {@link RenderTranscript} as flat lines for a {@link ForgeView}.
+ *
+ * A small convenience so a caller can pipe a projected transcript straight to
+ * `view.show`. Each block becomes a labelled line (or block of lines for
+ * multi-line bodies); turns are separated by a blank line. This lives next to the
+ * model because it is the natural pairing of "project, then show".
+ */
+export declare function formatTranscript(transcript: RenderTranscript): string[];

package/dist/types/swarm/coordinator.d.ts

@@ -0,0 +1,192 @@
+/**
+ * `Crew` — the swarm coordinator that ties the domain services together.
+ *
+ * A crew is a roster of teammate agents working a shared board of tickets,
+ * talking over one channel, with every coordination step narrated to an activity
+ * log. This module is the conductor that wires those services into a single
+ * driveable object:
+ *
+ *   - a {@link CrewManifest} — who is on the crew (the roster);
+ *   - a {@link TicketBoard}  — the shared, dependency-aware to-do list;
+ *   - a {@link Channel}      — the cursor-based mailbox teammates post on;
+ *   - an {@link ActivityLog} — the append-only transcript of what happened;
+ *   - optionally a {@link Workspace} — git-worktree isolation per teammate.
+ *
+ * The crew owns no `node:fs` locking, temp renames, or coercion of its own — all
+ * of that lives in the kernel under the services. What the coordinator adds is
+ * the *policy*: how ready tickets are matched to idle members, how a teammate
+ * agent is spawned to work a ticket, and how its result is folded back onto the
+ * board and the channel.
+ *
+ * The agent spawner is **injectable**. By default a member is backed by a real
+ * {@link createAgent} bound to the member's model and tool collection; tests pass
+ * a scripted fake agent so a round runs deterministically with no model or
+ * network. The coordinator only depends on the {@link Agent} handle's `submit`
+ * and `snapshot` surface, so a fake need only implement those.
+ *
+ * One round of work — {@link Crew.runRound} — is the heartbeat:
+ *   1. read the board's ready tickets and the idle members;
+ *   2. pair each ready ticket with an idle member;
+ *   3. for each pair: claim the ticket, spawn the member's agent, let it work the
+ *      ticket, post a `result` envelope, complete (or fail) the ticket, and
+ *      narrate every step to the activity log.
+ */
+import type { Agent } from "../runtime";
+import type { CrewMember, MemberDraft } from "./roster";
+import type { Ticket } from "./workboard";
+import type { CrewEvent } from "./telemetry/activity";
+import { Workspace } from "./isolation";
+/**
+ * The injectable factory that brings a teammate agent up for a member.
+ *
+ * The default ({@link defaultSpawnAgent}) builds a real {@link createAgent} bound
+ * to the member's model and {@link toolBox} collection. Tests substitute a
+ * scripted fake whose `submit` resolves to a canned snapshot, exercising the
+ * coordination logic without a model or the network.
+ */
+export type SpawnAgent = (member: CrewMember) => Agent;
+/** What a caller may set when standing up a crew. */
+export interface CrewOptions {
+    /**
+     * Root directory the crew persists under. The manifest, board, channel, and
+     * activity log are all rooted here; the directory is created lazily by the
+     * underlying kernel services.
+     */
+    readonly dir: string;
+    /**
+     * Optional git repository the crew isolates teammates into via a
+     * {@link Workspace}. When present the workspace is constructed (and exposed on
+     * {@link Crew.workspace}) so a host can provision per-teammate worktrees; the
+     * coordinator itself does not force isolation on every round.
+     */
+    readonly baseRepo?: string;
+    /**
+     * Override the agent spawner. Defaults to {@link defaultSpawnAgent} (a real
+     * {@link createAgent}); tests inject a scripted fake.
+     */
+    readonly spawnAgent?: SpawnAgent;
+    /** Injected clock, epoch ms — threaded into the board and activity log for tests. */
+    readonly now?: () => number;
+}
+/**
+ * A point-in-time aggregate of the crew's state, assembled from the board, the
+ * roster, and the activity log. This is what a status pane renders.
+ */
+export interface CrewStatus {
+    /** The crew id from the manifest (empty until {@link Crew.create}). */
+    readonly crewId: string;
+    /** The full roster, in enrollment order. */
+    readonly members: readonly CrewMember[];
+    /** Every ticket on the board, in insertion order. */
+    readonly tickets: readonly Ticket[];
+    /** The ticket ids currently workable (open, all deps done). */
+    readonly ready: readonly string[];
+    /** Count of tickets in each lifecycle state. */
+    readonly counts: {
+        readonly open: number;
+        readonly claimed: number;
+        readonly blocked: number;
+        readonly done: number;
+        readonly failed: number;
+    };
+    /** The full activity timeline, oldest first. */
+    readonly activity: readonly CrewEvent[];
+}
+/**
+ * The swarm coordinator. Construct with {@link createCrew}; it owns the four
+ * domain services and the agent spawner, and exposes the small set of verbs a
+ * host drives a crew through.
+ */
+export declare class Crew {
+    private readonly manifest;
+    private readonly board;
+    private readonly channel;
+    private readonly activity;
+    private readonly spawnAgent;
+    /** The optional git-worktree isolation seam (present only with a `baseRepo`). */
+    readonly workspace: Workspace | null;
+    /** The base repository worktrees are provisioned against, if any. */
+    readonly baseRepo: string | null;
+    private constructor();
+    /**
+     * Stand up a crew rooted at `dir`, wiring up the manifest, board, channel, and
+     * activity log (and a {@link Workspace} when `baseRepo` is given). The crew
+     * record is created eagerly so a fresh crew is immediately usable by
+     * {@link addMember}.
+     */
+    static open(opts: CrewOptions): Promise<Crew>;
+    /**
+     * Enroll a teammate and narrate the spawn to the activity log.
+     *
+     * Delegates the roster edit to the {@link CrewManifest}; on success a
+     * `member_spawned` event is recorded so the transcript reflects the new member.
+     */
+    addMember(draft: MemberDraft): Promise<CrewMember>;
+    /**
+     * Post a unit of work to the board and narrate it.
+     *
+     * Accepts the same draft shape the board's {@link TicketBoard.add} takes
+     * (title, optional body, optional deps); returns the admitted ticket. A
+     * `ticket_posted` event is recorded on success.
+     */
+    postTask(draft: TaskDraft): Promise<Ticket>;
+    /**
+     * Drive one round of work, returning the tickets that reached a terminal state
+     * this round.
+     *
+     * Reads the board's ready tickets and pairs each with an idle member (one
+     * ticket per member per round). For each pair it: claims the ticket for the
+     * member, spawns the member's agent, lets the agent work the ticket, posts a
+     * `result` envelope on the channel, completes (or, on a thrown error, fails)
+     * the ticket, and records the corresponding activity events. A round with no
+     * ready work or no idle members is a no-op that returns an empty list.
+     */
+    runRound(): Promise<RoundOutcome>;
+    /**
+     * Assemble the crew's current state from the board, roster, and activity log.
+     * A pure read across the three services — it takes no locks and mutates
+     * nothing.
+     */
+    status(): Promise<CrewStatus>;
+    /**
+     * Work a single ticket with a single member, end to end.
+     *
+     * Claims the ticket (recording `ticket_claimed`), spawns the member's agent and
+     * runs it over the ticket brief, posts a `result` envelope back to the
+     * coordinator (recording `message_sent`), then completes the ticket (recording
+     * `ticket_done`). Any throw while the agent runs fails the ticket instead
+     * (recording `ticket_failed`), so one bad teammate cannot wedge the round.
+     */
+    private workOne;
+    /** The set of member ids currently holding a claimed (or blocked) ticket. */
+    private busyMemberIds;
+}
+/** The result of one {@link Crew.runRound}: which tickets settled and how. */
+export interface RoundOutcome {
+    /** Tickets that reached `done` this round. */
+    readonly completed: readonly Ticket[];
+    /** Tickets that reached `failed` this round. */
+    readonly failed: readonly Ticket[];
+}
+/** A ticket draft accepted by {@link Crew.postTask} (mirrors the board's draft). */
+export interface TaskDraft {
+    /** Short human-facing summary (required). */
+    readonly title: string;
+    /** Full task description; defaults to empty. */
+    readonly body?: string;
+    /** Ids of tickets that must complete first; defaults to none. */
+    readonly deps?: readonly string[];
+}
+/**
+ * Stand up a crew. The host-facing factory; see {@link CrewOptions} for the knobs
+ * and {@link Crew} for the verbs.
+ */
+export declare function createCrew(opts: CrewOptions): Promise<Crew>;
+/**
+ * The default agent spawner: a real {@link createAgent} bound to the member's
+ * model and tool collection. The member's `toolCollection` (a structural twin of
+ * the capabilities {@link ToolCollection}) is handed straight to {@link toolBox};
+ * an unset collection defaults to `read-only` (the safe floor). The member's
+ * pinned model — or {@link DEFAULT_MEMBER_MODEL} — backs the run.
+ */
+export declare function defaultSpawnAgent(member: CrewMember): Agent;

package/dist/types/swarm/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The swarm layer — public surface.
+ *
+ * The crew/swarm coordination stack, assembled into one import site. The
+ * coordinator ({@link Crew} / {@link createCrew}) ties together four domain
+ * services — each a thin wrapper over the frozen kernel — plus an optional
+ * git-worktree isolation seam:
+ *
+ *   - {@link CrewManifest} — the roster (who is on the crew);
+ *   - {@link TicketBoard}  — the dependency-aware shared task store;
+ *   - {@link Channel}      — the cursor-based mailbox;
+ *   - {@link ActivityLog}  — the append-only coordination transcript;
+ *   - {@link Workspace}    — per-teammate git-worktree isolation.
+ *
+ * The kernel primitives the services are built on ({@link JsonCell},
+ * {@link JsonlLog}, {@link newId}, {@link SwarmFault}) are re-exported too, so a
+ * host that wants to compose its own service over the same foundation can reach
+ * them from one place.
+ */
+export { createCrew, Crew, defaultSpawnAgent } from "./coordinator";
+export type { CrewOptions, CrewStatus, RoundOutcome, TaskDraft, SpawnAgent, } from "./coordinator";
+export { CrewManifest, ModelPolicy } from "./roster";
+export type { CrewMember, CrewRecord, MemberDraft, CrewToolCollection, } from "./roster";
+export { TicketBoard, ticketSchema, ticketStatuses, DepGraph } from "./workboard";
+export type { Ticket, TicketStatus, TicketDraft } from "./workboard";
+export { Channel, encode, decode, ENVELOPE_SCHEMA, ENVELOPE_TYPES } from "./postbox";
+export type { Envelope, EnvelopeType, PayloadOf } from "./postbox";
+export { Workspace, nodeRunner } from "./isolation";
+export type { WorktreeRef, WorktreeEntry, CreateOptions, RemoveOptions, ShellRunner, RunResult, } from "./isolation";
+export { ActivityLog, CREW_EVENT_KINDS } from "./telemetry/activity";
+export type { CrewEvent, CrewEventKind, CrewEventInput } from "./telemetry/activity";
+export { JsonCell, JsonlLog, newId, SwarmFault, swarmFault } from "./kernel";
+export type { GuardOptions, TreeNode, SwarmFaultKind, } from "./kernel";

package/dist/types/swarm/isolation/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * The swarm isolation layer — public surface.
+ *
+ * Teammates run in isolated git worktrees so each can mutate its own working
+ * tree and branch without colliding with its peers. This module exposes the
+ * provisioning primitive ({@link Workspace}) and the injectable shell seam it
+ * runs git through ({@link ShellRunner} / {@link nodeRunner}).
+ *
+ * Git failures surface as `isolation`-kind {@link import("../kernel").SwarmFault}s.
+ */
+export { Workspace } from "./worktree";
+export type { WorktreeRef, WorktreeEntry, CreateOptions, RemoveOptions, } from "./worktree";
+export { nodeRunner } from "./runner";
+export type { ShellRunner, RunResult } from "./runner";

package/dist/types/swarm/isolation/runner.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The shell seam the {@link import("./worktree").Workspace} runs git through.
+ *
+ * Worktree provisioning is the one place in the isolation layer that has to
+ * shell out — `git worktree add/list/remove` has no in-process equivalent. To
+ * keep that I/O testable, the {@link Workspace} never reaches for
+ * `node:child_process` itself; it asks for a {@link ShellRunner} and invokes
+ * git through it. Tests inject a hand-written fake runner (asserting on the
+ * exact command strings, returning scripted output and exit codes); production
+ * code injects {@link nodeRunner}, a thin wrapper over `execFile` with the
+ * shell disabled.
+ *
+ * A run never throws on a non-zero exit. The runner always resolves with a
+ * {@link RunResult} carrying `{ stdout, stderr, code }`; it is the
+ * {@link Workspace}'s job to inspect `code` and translate a git failure into a
+ * typed `isolation` {@link import("../kernel").SwarmFault}. This keeps the
+ * seam dumb (it transports bytes and an exit status, nothing more) and the
+ * policy (what counts as a failure, what the error should say) in one place.
+ */
+/** The outcome of one shelled-out command. */
+export interface RunResult {
+    /** Everything the command wrote to stdout, decoded as UTF-8. */
+    readonly stdout: string;
+    /** Everything the command wrote to stderr, decoded as UTF-8. */
+    readonly stderr: string;
+    /**
+     * The process exit code. `0` is success; any other value is a failure the
+     * caller is expected to map onto a fault. A process killed by a signal (no
+     * numeric code) is reported as `null`.
+     */
+    readonly code: number | null;
+}
+/**
+ * A function that runs one command and resolves with its captured output and
+ * exit status. It must *not* reject on a non-zero exit — a failed command is a
+ * resolved {@link RunResult} with a non-zero `code`. Rejection is reserved for
+ * the runner itself being unable to spawn anything (e.g. the binary is
+ * missing), which the {@link Workspace} also folds into an `isolation` fault.
+ */
+export interface ShellRunner {
+    /**
+     * Execute `command` and resolve with its result. `command` is the full
+     * command line as a single string (e.g. `git worktree list --porcelain`).
+     * The optional `cwd` is the directory to run it in; when omitted the runner's
+     * own default applies.
+     */
+    exec(command: string, cwd?: string): Promise<RunResult>;
+}
+/**
+ * The production {@link ShellRunner}: a thin wrapper over `execFile`.
+ *
+ * The command string is split on whitespace into an argv vector and handed to
+ * `execFile` with **no shell** — there is no `/bin/sh -c`, so command
+ * substitution, globbing, pipes, and quoting do not apply. Every argument this
+ * layer ever passes to git is a literal token (a branch name, an absolute
+ * path, a flag), so the naive split is exactly right and the shell-less spawn
+ * removes an injection surface. A non-zero exit resolves (it does not reject):
+ * `execFile`'s error object still carries `stdout`/`stderr`/`code`, which we
+ * forward verbatim.
+ */
+export declare const nodeRunner: ShellRunner;

package/dist/types/swarm/isolation/worktree.d.ts

@@ -0,0 +1,142 @@
+/**
+ * `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;
+}