/** The heading the block carries, and the marker a reader looks for. */
export declare const SCRATCH_PATH_BLOCK_HEADING = "Scratch path (REQUIRED \u2014 absolute path; never a cwd-relative redirect)";
/** Where the absolute path goes in the template. */
export declare const SCRATCH_DIR_PLACEHOLDER = "{{scratchDir}}";
/**
 * The canonical block, verbatim, with the path left as a placeholder: the
 * path differs for every dispatch, so the template is what can be pinned
 * against the reference file's fenced copy.
 */
export declare const SCRATCH_PATH_BLOCK_TEMPLATE = "Scratch path (REQUIRED \u2014 absolute path; never a cwd-relative redirect)\n\nWrite every temporary file for this task under this ABSOLUTE path:\n{{scratchDir}}\n\nNever redirect to a path that depends on the working directory \u2014 `2> out.err`, `> run.log`, `./scratch/`. A cwd-relative redirect writes wherever the task happens to `cd`: measured 2026-10-02, five zero-byte `*.err` captures landed at the repository root and were committed, and `git status` stayed clean because the files were tracked. Use the absolute path above; it lives under the session's runtime dir, which is gitignored, so nothing written there can be committed by accident.\n";
/**
 * The path in the form every shell accepts: forward slashes on every
 * platform.
 *
 * A Windows path spelled with backslashes is an ESCAPE SEQUENCE to a POSIX
 * shell — `> D:\repo\x.log` there writes a file named `D:repox.log` into the
 * CURRENT directory, which is the exact leak this block exists to stop. The
 * forward-slash form is accepted by bash, cmd, PowerShell and Node alike.
 */
export declare function toShellPath(path: string): string;
/**
 * The absolute scratch directory for one dispatch.
 *
 * Pure, and independent of the working directory: the only input that is not
 * the project root and the two id segments is the filesystem separator. A
 * RELATIVE project root is resolved against the cwd — the dispatch CLI passes
 * an absolute one (`options.project ?? process.cwd()`), and the emitted path
 * is absolute either way.
 */
export declare function resolveScratchDir(projectRoot: string, sid: string, role: string): string;
/**
 * The block for one dispatch, with the absolute path substituted.
 *
 * Pure. The replacement is done with a FUNCTION so a path that contains a
 * `$` sequence is inserted literally rather than read as a replacement
 * pattern.
 */
export declare function buildScratchPathBlock(scratchDir: string): string;
/** The outcome of creating the scratch directory. */
export type ScratchDirState = {
    readonly ok: true;
} | {
    readonly ok: false;
    readonly reason: string;
};
/**
 * Create the scratch directory so the FIRST redirect into it works.
 *
 * A redirect into a directory that does not exist fails, and an agent that
 * hits that failure is an agent that may fall back to a cwd-relative path —
 * the leak this block exists to stop. The failure is reported rather than
 * swallowed: the caller turns it into a dispatch warning, so a scratch
 * directory that could not be created is visible instead of silent.
 */
export declare function ensureScratchDir(scratchDir: string): ScratchDirState;
/** What one dispatch's prompt gains. */
export type ScratchPathInjection = {
    /** The block, with the absolute path substituted. */
    readonly block: string;
    /** The absolute scratch directory, with the platform's own separators. */
    readonly scratchDir: string;
    /** Null when the directory exists; the reason when it does not. */
    readonly warning: string | null;
};
/**
 * The scratch-path block for one dispatch, and the one side effect that makes
 * it usable: the directory is created so the first redirect into it works.
 */
export declare function buildScratchPathInjection(input: {
    projectRoot: string;
    sid: string;
    role: string;
}): ScratchPathInjection;