framework/dist/worktrees.d.ts

The (AI) Framework: turnkey, zero-config AI orchestration that wraps a coding-agent CLI (Claude Code) as a black box and takes you from an idea to a running app. Vite for AI.

import { type AgentStatus } from './store/index.js';
/** A retained worktree and the agent that left it behind (#752). */
export interface WorktreeRow {
    /** The agent id, which is also the worktree's directory name. */
    agentId: string;
    /** The branch the agent's work landed on, when its meta recorded one (#799). */
    branch?: string;
    /** How the agent that left this checkout ended, or `running` while it is still going. */
    status?: AgentStatus;
    /** Size on disk in bytes, absent for a live agent (its tree is still changing) or when unreadable. */
    sizeBytes?: number;
    /** True while the agent owning this checkout is still going: it is in use, not retained. */
    live: boolean;
}
/** Why a worktree was left in place by {@link pruneProjectWorktrees}. */
export interface SkippedWorktree {
    agentId: string;
    reason: string;
}
/** What {@link pruneProjectWorktrees} did. */
export interface PruneResult {
    removed: string[];
    skipped: SkippedWorktree[];
}
/** The outcome of {@link removeProjectWorktree}. */
export type RemoveResult = {
    ok: true;
} | {
    ok: false;
    error: string;
};
/** Surface-specific work {@link removeProjectWorktree} does once removal is decided on. */
export interface RemoveWorktreeOptions {
    /**
     * Run after the safety checks pass and the work is committed, just before the checkout goes.
     * The dashboard stops the preview serving that tree here (#797); the CLI has none to stop.
     */
    beforeRemove?: (agentId: string) => Promise<void>;
}
/**
 * The worktrees a project still has on disk (#752), newest first — the same view the dashboard's
 * retained-worktrees list is built from, through the same store reads, so the CLI is a second
 * surface rather than a second behaviour.
 *
 * A live agent's checkout is included and flagged rather than hidden: "what is this directory and
 * why can I not remove it" is exactly the question the list has to answer.
 */
export declare function listProjectWorktrees(cwd: string, opts?: {
    sizes?: boolean;
}): Promise<WorktreeRow[]>;
/**
 * Remove one retained worktree (#752/#737/E5): the one implementation behind every surface that
 * removes one — the sweep, teardown, and the dashboard's Remove button (#982).
 *
 * **One rule: only what is on the remote may go.** The work is committed to the session's branch,
 * the branch is pushed, and the checkout is removed only once the remote has it. Every deletion is
 * therefore recoverable, and nothing local is ever the last copy of anything. It replaced three
 * interacting rules that each asked *what state did this session end in* — a clean finish removes
 * the checkout, a failure or stop keeps it, a merged branch reclaims it later via two different
 * "landed" signals — where the question that actually matters is *is this recoverable yet*. There
 * is one failure mode now, and it is legible: the push did not land, so the checkout stays and the
 * reason says why.
 *
 * The push serves the rule; it is not a licence to publish. A session armed to publish nothing
 * (`handoff: local`, B5/#1379) said its branch must not reach the remote, so its unpushed checkout
 * is kept — the same outcome as a repo with no remote — rather than pushed to make it removable.
 * Deciding otherwise would have teardown publish the very branch the agent's own handoff just
 * declined to. Nothing is committed on the way to that refusal either — a kept checkout is a
 * place someone works, and the sweep re-offers it every pass — so it goes only from a clean tree
 * on a pushed tip. And a record that cannot be read keeps the checkout too: unreadable is not
 * "publish freely".
 *
 * Refuses while the agent is still going — an agent's checkout is where its agent is working, and Stop
 * is how you end an agent, not pulling the floor out from under it.
 */
export declare function removeProjectWorktree(cwd: string, agentId: string, opts?: RemoveWorktreeOptions): Promise<RemoveResult>;
/** The outcome of {@link deleteProjectAgent}. */
export type DeleteAgentResult = {
    ok: true;
} | {
    ok: false;
    error: string;
};
/** Surface-specific work {@link deleteProjectAgent} does, and the file-removal seam for tests. */
export interface DeleteAgentOptions {
    /** Run before the worktree comes off disk (stop a preview serving it, as removal does). */
    beforeRemove?: (agentId: string) => Promise<void>;
    /** Remove one file, tolerant of an absent one. Defaults to `rm(path, { force: true })`. */
    removeFile?: (path: string) => Promise<void>;
}
/**
 * Delete a session (#1032): take it out of the dashboard, records and all.
 *
 * This is the sibling of {@link removeProjectWorktree}, and the difference is the whole point.
 * Remove-worktree reclaims the checkout on disk and keeps the session — its row, its replayable
 * log — because the history was already archived. Delete removes that archive too: the agent meta
 * (`<id>.json`, what the rail lists) and its event log (`<id>.jsonl`, what replays), wherever they
 * are filed, so the row is gone for good. It is the one destructive-of-history action, which is
 * why the surfaces that call it confirm first. Since #1179 that archive is committed, so the files
 * go but the deletion is itself a change git will record.
 *
 * What it deliberately leaves is git's, not the dashboard's: the branch `tf-agent-<id>`
 * (or the name the agent gave it) and its commits. Deleting a branch that may carry merged work
 * or an open PR is not a thing a
 * dashboard action should do silently, so the branch stays and delete means "remove from the
 * dashboard", not "erase every trace".
 *
 * Refuses while the agent is still going — Stop is how an agent ends. Any uncommitted work in the
 * worktree is discarded with it, which is the intent here (the session is being thrown away),
 * unlike remove-worktree, which commits that work to the kept branch first.
 */
export declare function deleteProjectAgent(cwd: string, agentId: string, opts?: DeleteAgentOptions): Promise<DeleteAgentResult>;
/**
 * Remove every retained worktree whose run is not live (#752): the "clean all of this up" case.
 * A live agent keeps its checkout and is reported as skipped, so the count always adds up to what
 * the list showed — and so does one whose branch could not reach the remote (E5).
 */
export declare function pruneProjectWorktrees(cwd: string): Promise<PruneResult>;
//# sourceMappingURL=worktrees.d.ts.map