import type { RunDirectoryPaths, RunDirectorySnapshot } from "./runDir.js";
/**
 * Attaching a filesystem snapshot to a run directory, at `workdir/`, with a
 * sidecar `workdir.json` recording when the snapshot was taken and where
 * from — a workdir attached after the fact may postdate the run, and a grader
 * deserves to know. The plan is pure; replacement (`replace: true`) is carried
 * out inside the apply step through `safeDeleteDirectoryWithin`, so no caller
 * ever deletes first.
 */
export declare class WorkdirAttachmentError extends Error {
}
export type WorkdirAttachmentRequest = {
    sourceDir: string;
    replace?: boolean;
    /** A directory inside `sourceDir` to leave out of the copy, on top of the
     *  run directory itself: the group a captured run is being written into. */
    excludeDir?: string;
};
export type WorkdirAttachmentPlan = {
    sourceDir: string;
    target: string;
    sidecar: string;
    excludeDirs: string[];
    status: "add" | "replace";
};
export type WorkdirSidecar = {
    snapshotAt: string;
    source: string;
};
export declare function planWorkdirAttachment(snapshot: RunDirectorySnapshot, request: WorkdirAttachmentRequest, paths: RunDirectoryPaths): WorkdirAttachmentPlan;
/** @internal Copies the tree and writes the sidecar. Caller holds the lock. */
export declare function applyWorkdirAttachment(paths: RunDirectoryPaths, plan: WorkdirAttachmentPlan, snapshotAt: string): void;