humanish 0.104.3 → 0.106.0

package/dist/run/participant-records.js

@@ -0,0 +1,63 @@
+// The run bundle's participant records, written and read. A route describes each participant (its
+// record and stream fields, its events) and these functions give them the bundle's saved shape and
+// field names; readers ask them for the ids a saved record carries. This module and run/bundle.ts
+// (its types and bundleHead) and run/streams.ts are where those contract spellings live.
+/** Ids a route chose itself, for routes whose ids are not the `sim-NNN` default. */
+export function participantIdsOf(recordId, streamId) {
+    return { recordId, streamId };
+}
+/** The default ids of the participant at a 0-based position: `sim-001` and `stream-001` first. */
+export function participantIds(position) {
+    const ordinal = String(position + 1).padStart(3, "0");
+    return participantIdsOf(`sim-${ordinal}`, `stream-${ordinal}`);
+}
+/** A participant's record, at its 1-based place in the bundle, with its one stream. */
+export function participantRecord(ids, place, fields) {
+    return {
+        id: ids.recordId,
+        index: place,
+        personaId: fields.personaId,
+        scenarioId: fields.scenarioId,
+        status: fields.status,
+        streamKind: fields.streamKind,
+        mode: fields.mode,
+        progress: fields.progress,
+        currentStep: fields.currentStep,
+        summary: fields.summary,
+        streamIds: [ids.streamId],
+        startedAt: fields.startedAt,
+        updatedAt: fields.updatedAt,
+    };
+}
+/**
+ * A participant's stream. `participantId` is the route's own participant id (a fan-out lane's id),
+ * saved right after the record id when the route has one.
+ */
+export function participantStream(ids, fields, participantId) {
+    return {
+        id: ids.streamId,
+        simId: ids.recordId,
+        ...(participantId === undefined ? {} : { laneId: participantId }),
+        ...fields,
+    };
+}
+/** An event about one participant. */
+export function participantEvent(ids, event) {
+    return { ...event, simId: ids.recordId, streamId: ids.streamId };
+}
+/** The ids a provider resource saves for the participant whose sandbox it is. */
+export function participantResourceIds(ids, participantId) {
+    return { simId: ids.recordId, streamId: ids.streamId, laneId: participantId };
+}
+/** The record id a saved stream belongs to. */
+export function recordIdOf(stream) {
+    return stream.simId;
+}
+/** The record id a saved event names, when it names one. */
+export function eventRecordIdOf(event) {
+    return event.simId;
+}
+/** The participant id an adapter recorded on a saved stream (a fan-out lane id), when it has one. */
+export function streamParticipantIdOf(stream) {
+    return stream.laneId;
+}

package/dist/run/participant.d.ts

@@ -0,0 +1,29 @@
+import type { ActorPersonaRef } from "../actors/contract.js";
+import type { Participant } from "../lab/plan-participants.js";
+import type { RunParticipantAssignment } from "./streams.js";
+/**
+ * A planned participant resolved for one run: the plan's record unchanged, plus what the route
+ * derives before the participant starts. Every field about who the participant is lives on
+ * `planned`; this record adds only the bundle ids, the resolved persona and the prompt.
+ */
+export interface ResolvedParticipant<P extends Participant = Participant> {
+    /** Identity, persona id, mission and focus, labels and the route's own fields, from the plan. */
+    readonly planned: P;
+    /** Bundle ids from `planned.index`: `sim-NNN` and `stream-NNN`. */
+    readonly recordId: string;
+    readonly streamId: string;
+    /** The compiled persona brief. Evidence scrubbing replaces it before any bundle is written. */
+    persona: ActorPersonaRef;
+    /** The prompt the model reads. */
+    readonly instructions: string;
+    /** Redacted copy of the prompt for the bundle; set when the route scrubs its evidence. */
+    evidenceInstructions?: string;
+    /** What the participant was asked to do, as the bundle records it: mission, focus, task goals. */
+    evidenceAssignment?: RunParticipantAssignment;
+}
+/** Resolve a planned participant: bundle ids from its index, plus the route's persona and prompt. */
+export declare function resolveParticipant<P extends Participant>(planned: P, resolved: {
+    persona: ActorPersonaRef;
+    instructions: string;
+    evidenceAssignment: RunParticipantAssignment;
+}): ResolvedParticipant<P>;

package/dist/run/participant.js

@@ -0,0 +1,12 @@
+/** Resolve a planned participant: bundle ids from its index, plus the route's persona and prompt. */
+export function resolveParticipant(planned, resolved) {
+    const ordinal = String(planned.index + 1).padStart(3, "0");
+    return {
+        planned,
+        recordId: `sim-${ordinal}`,
+        streamId: `stream-${ordinal}`,
+        persona: resolved.persona,
+        instructions: resolved.instructions,
+        evidenceAssignment: resolved.evidenceAssignment,
+    };
+}

package/dist/run/paths.d.ts

@@ -0,0 +1,79 @@
+export declare const RUNS_RELATIVE_ROOT: string;
+interface RunArtifactPaths {
+    absoluteRunRoot: string;
+    relativeRunRoot: string;
+    absoluteLatestPointer: string;
+    relativeLatestPointer: string;
+}
+export interface PreparedRunArtifactPaths extends RunArtifactPaths {
+    readonly physicalLatestPointer: string;
+    readonly physicalRunRoot: string;
+    readonly physicalRunsRoot: string;
+    readonly runRootIdentity: FileIdentity;
+    readonly runsRootIdentity: FileIdentity;
+}
+export interface FileIdentity {
+    readonly birthtimeNs: bigint;
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+export interface LatestRunPathPointer {
+    runId: string;
+    path: string;
+}
+/**
+ * Run ids are directory names, not paths. Keep the accepted grammar broad so
+ * existing runs remain readable while rejecting every path-shaped input.
+ */
+export declare function isSafeRunIdSegment(runId: string): boolean;
+export declare function resolveRunsRoot(cwdInput: string): string;
+export declare function prepareRunArtifactPaths(cwdInput: string, runId: string): Promise<PreparedRunArtifactPaths>;
+/** A new run's id names a directory that already exists. */
+export interface RunIdInUse {
+    ok: false;
+    code: "HUMANISH_RUN_ID_IN_USE";
+    message: string;
+}
+/**
+ * Create and bind the directory of a new run. The run directory is made with one non-recursive
+ * mkdir, so of two starts with the same id exactly one gets it. Any existing entry under that id
+ * (a finished run, an interrupted one that left only sandbox receipts, a symlink) refuses the
+ * start before anything is written, so a caller-supplied id can never overwrite another run's
+ * status or evidence. Code that reads or appends to an existing run binds it with
+ * `bindExistingRunArtifactPaths` instead.
+ */
+export declare function createRunArtifactPaths(cwdInput: string, runId: string): Promise<{
+    ok: true;
+    paths: PreparedRunArtifactPaths;
+} | RunIdInUse>;
+export declare function validatePreparedRunArtifactPaths(prepared: PreparedRunArtifactPaths): Promise<PreparedRunArtifactPaths>;
+/**
+ * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
+ * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * resolve is returned as given, so the caller still reports it missing.
+ */
+export declare function resolvePhysicalCwd(cwdInput: string): Promise<string>;
+/** The physical project directory of a prepared run (`<project>/.humanish/runs/<id>`). */
+export declare function physicalCwdOf(prepared: PreparedRunArtifactPaths): string;
+/** The run id of a prepared run: its directory name. */
+export declare function runIdOf(prepared: PreparedRunArtifactPaths): string;
+/** Cheap revalidation for repeated contained reads/writes within one prepared run. */
+export declare function validatePreparedRunRootIdentity(prepared: PreparedRunArtifactPaths): Promise<PreparedRunArtifactPaths>;
+/** Bind an already-existing safe run as a new identity; this is not prior-preparation proof. */
+export declare function bindExistingRunArtifactPaths(cwdInput: string, runId: string): Promise<PreparedRunArtifactPaths>;
+export declare function resolveExistingRunDirectory(cwdInput: string, runId: string): Promise<string | null>;
+/**
+ * A latest pointer is valid only when both fields identify the same direct
+ * child of .humanish/runs. Callers must never use pointer.path directly.
+ */
+export declare function resolveLatestRunDirectory(cwdInput: string, pointer: LatestRunPathPointer): string | null;
+export declare function prepareHumanishStorageDirectory(cwdInput: string, ...segments: string[]): Promise<string>;
+export declare function resolveExistingHumanishStorageDirectory(cwdInput: string, ...segments: string[]): Promise<string | null>;
+export declare function isPathInside(rootInput: string, candidateInput: string): boolean;
+/** Missing is fine; anything present must be a single-link regular file. */
+export declare function assertRegularFileOrMissing(filePath: string, subject?: string): Promise<void>;
+/** The directory is still the physical, non-symlink directory captured as `identity`. */
+export declare function assertDirectoryIdentity(directory: string, identity: FileIdentity, changedMessage?: string): Promise<void>;
+export declare function isRiskyPublicArtifactPath(relativePath: string): boolean;
+export declare function isLocalEvidenceArtifactPath(value: string): boolean;
+export {};

package/dist/run/paths.js

@@ -0,0 +1,356 @@
+import { lstat, mkdir, readdir, realpath, rmdir } from "node:fs/promises";
+import path from "node:path";
+import { isNodeError } from "./type-guards.js";
+export const RUNS_RELATIVE_ROOT = path.join(".humanish", "runs");
+const LATEST_RUN_RELATIVE_PATH = path.join(RUNS_RELATIVE_ROOT, "latest.json");
+/**
+ * Run ids are directory names, not paths. Keep the accepted grammar broad so
+ * existing runs remain readable while rejecting every path-shaped input.
+ */
+export function isSafeRunIdSegment(runId) {
+    return (runId.length > 0 &&
+        runId !== "." &&
+        runId !== ".." &&
+        !runId.includes("/") &&
+        !runId.includes("\\") &&
+        !runId.includes("\0"));
+}
+export function resolveRunsRoot(cwdInput) {
+    return path.resolve(cwdInput, RUNS_RELATIVE_ROOT);
+}
+function resolveRunDirectory(cwdInput, runId) {
+    if (!isSafeRunIdSegment(runId)) {
+        throw new Error("Run id must be one non-empty path segment.");
+    }
+    const runsRoot = resolveRunsRoot(cwdInput);
+    const runRoot = path.resolve(runsRoot, runId);
+    if (!isPathInside(runsRoot, runRoot) || path.dirname(runRoot) !== runsRoot) {
+        throw new Error("Run directory must stay inside the humanish runs root.");
+    }
+    return runRoot;
+}
+function tryResolveRunDirectory(cwdInput, runId) {
+    try {
+        return resolveRunDirectory(cwdInput, runId);
+    }
+    catch {
+        return null;
+    }
+}
+function resolveRunArtifactPaths(cwdInput, runId) {
+    if (runId === "latest.json") {
+        throw new Error("Run id is reserved; choose a different run id.");
+    }
+    const absoluteRunRoot = resolveRunDirectory(cwdInput, runId);
+    return {
+        absoluteRunRoot,
+        relativeRunRoot: path.join(RUNS_RELATIVE_ROOT, runId),
+        absoluteLatestPointer: path.resolve(cwdInput, LATEST_RUN_RELATIVE_PATH),
+        relativeLatestPointer: LATEST_RUN_RELATIVE_PATH,
+    };
+}
+export async function prepareRunArtifactPaths(cwdInput, runId) {
+    const paths = resolveRunArtifactPaths(cwdInput, runId);
+    const prepared = await prepareHumanishStorageDirectory(cwdInput, "runs", runId);
+    if (prepared !== paths.absoluteRunRoot) {
+        throw new Error("Run directory resolved outside the expected storage root.");
+    }
+    await assertNoSymlinkDescendants(prepared);
+    await assertRegularFileOrMissing(paths.absoluteLatestPointer);
+    return validatePreparedRunArtifactPaths(await capturePreparedRunArtifactPaths(paths, prepared));
+}
+/**
+ * Create and bind the directory of a new run. The run directory is made with one non-recursive
+ * mkdir, so of two starts with the same id exactly one gets it. Any existing entry under that id
+ * (a finished run, an interrupted one that left only sandbox receipts, a symlink) refuses the
+ * start before anything is written, so a caller-supplied id can never overwrite another run's
+ * status or evidence. Code that reads or appends to an existing run binds it with
+ * `bindExistingRunArtifactPaths` instead.
+ */
+export async function createRunArtifactPaths(cwdInput, runId) {
+    const paths = resolveRunArtifactPaths(cwdInput, runId);
+    const runsRoot = await prepareHumanishStorageDirectory(cwdInput, "runs");
+    if (runsRoot !== path.dirname(paths.absoluteRunRoot)) {
+        throw new Error("Run directory resolved outside the expected storage root.");
+    }
+    // A pointer that is not a regular file refuses the start before the directory exists.
+    await assertRegularFileOrMissing(paths.absoluteLatestPointer);
+    const runDirectory = path.join(await realpath(runsRoot), runId);
+    try {
+        await mkdir(runDirectory);
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "EEXIST") {
+            return {
+                ok: false,
+                code: "HUMANISH_RUN_ID_IN_USE",
+                message: `Run id ${runId} is already in use: ${paths.relativeRunRoot} exists. Choose a new run id, or omit it to mint one.`,
+            };
+        }
+        throw error;
+    }
+    try {
+        return { ok: true, paths: await prepareRunArtifactPaths(cwdInput, runId) };
+    }
+    catch (error) {
+        // A failed preparation releases the id. The directory is still empty, and a non-recursive
+        // rmdir leaves it in place if anything was written into it meanwhile.
+        await rmdir(runDirectory).catch(() => undefined);
+        throw error;
+    }
+}
+export async function validatePreparedRunArtifactPaths(prepared) {
+    await validatePreparedRunRootIdentity(prepared);
+    await assertNoSymlinkDescendants(prepared.physicalRunRoot);
+    await assertRegularFileOrMissing(prepared.physicalLatestPointer);
+    return prepared;
+}
+/**
+ * The physical project directory for a caller's cwd, bound before a run is resolved so a symlinked
+ * cwd retargeted later cannot move reads or writes to another project (#1012). A cwd that does not
+ * resolve is returned as given, so the caller still reports it missing.
+ */
+export async function resolvePhysicalCwd(cwdInput) {
+    const requested = path.resolve(cwdInput);
+    return realpath(requested).catch(() => requested);
+}
+/** The physical project directory of a prepared run (`<project>/.humanish/runs/<id>`). */
+export function physicalCwdOf(prepared) {
+    return path.dirname(path.dirname(prepared.physicalRunsRoot));
+}
+/** The run id of a prepared run: its directory name. */
+export function runIdOf(prepared) {
+    return path.basename(prepared.physicalRunRoot);
+}
+/** Cheap revalidation for repeated contained reads/writes within one prepared run. */
+export async function validatePreparedRunRootIdentity(prepared) {
+    const [lexicalRunsRoot, lexicalRunRoot] = await Promise.all([
+        realpath(path.dirname(prepared.absoluteRunRoot)),
+        realpath(prepared.absoluteRunRoot),
+    ]);
+    if (lexicalRunsRoot !== prepared.physicalRunsRoot ||
+        lexicalRunRoot !== prepared.physicalRunRoot) {
+        throw new Error("Prepared humanish run storage changed physical destination.");
+    }
+    await Promise.all([
+        assertDirectoryIdentity(prepared.physicalRunsRoot, prepared.runsRootIdentity),
+        assertDirectoryIdentity(prepared.physicalRunRoot, prepared.runRootIdentity),
+    ]);
+    return prepared;
+}
+/** Bind an already-existing safe run as a new identity; this is not prior-preparation proof. */
+export async function bindExistingRunArtifactPaths(cwdInput, runId) {
+    const paths = resolveRunArtifactPaths(cwdInput, runId);
+    const existing = await resolveExistingRunDirectory(cwdInput, runId);
+    if (!existing || existing !== paths.absoluteRunRoot) {
+        throw new Error("Run directory is not an existing humanish run directory.");
+    }
+    await assertNoSymlinkDescendants(existing);
+    await assertRegularFileOrMissing(paths.absoluteLatestPointer);
+    return validatePreparedRunArtifactPaths(await capturePreparedRunArtifactPaths(paths, existing));
+}
+export async function resolveExistingRunDirectory(cwdInput, runId) {
+    const expected = tryResolveRunDirectory(cwdInput, runId);
+    if (!expected) {
+        return null;
+    }
+    const existing = await resolveExistingHumanishStorageDirectory(cwdInput, "runs", runId);
+    return existing === expected ? existing : null;
+}
+/**
+ * A latest pointer is valid only when both fields identify the same direct
+ * child of .humanish/runs. Callers must never use pointer.path directly.
+ */
+export function resolveLatestRunDirectory(cwdInput, pointer) {
+    const expected = tryResolveRunDirectory(cwdInput, pointer.runId);
+    if (!expected || !isProjectRelativePath(pointer.path)) {
+        return null;
+    }
+    const declared = path.resolve(cwdInput, pointer.path);
+    return declared === expected ? expected : null;
+}
+export async function prepareHumanishStorageDirectory(cwdInput, ...segments) {
+    const prepared = await walkHumanishStorage(cwdInput, segments, true);
+    if (!prepared) {
+        throw new Error("humanish storage directory could not be created.");
+    }
+    return prepared;
+}
+export async function resolveExistingHumanishStorageDirectory(cwdInput, ...segments) {
+    return walkHumanishStorage(cwdInput, segments, false);
+}
+export function isPathInside(rootInput, candidateInput) {
+    const root = path.resolve(rootInput);
+    const candidate = path.resolve(candidateInput);
+    const relative = path.relative(root, candidate);
+    return (relative === "" ||
+        (relative !== ".." && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative)));
+}
+function isProjectRelativePath(value) {
+    const parts = value.replace(/\\/g, "/").split("/");
+    return (value.length > 0 &&
+        !path.isAbsolute(value) &&
+        !path.posix.isAbsolute(value) &&
+        !path.win32.isAbsolute(value) &&
+        !value.includes("\0") &&
+        !parts.some((part) => part === "." || part === ".."));
+}
+async function walkHumanishStorage(cwdInput, segments, create) {
+    assertSafeStorageSegments(segments);
+    let current = path.resolve(cwdInput);
+    for (const segment of [".humanish", ...segments]) {
+        current = path.join(current, segment);
+        let stats;
+        try {
+            stats = await lstat(current);
+        }
+        catch (error) {
+            if (!isNodeError(error) || error.code !== "ENOENT") {
+                throw error;
+            }
+            if (!create) {
+                return null;
+            }
+            try {
+                await mkdir(current);
+            }
+            catch (mkdirError) {
+                if (!isNodeError(mkdirError) || mkdirError.code !== "EEXIST") {
+                    throw mkdirError;
+                }
+            }
+            stats = await lstat(current);
+        }
+        if (stats.isSymbolicLink()) {
+            throw new Error("humanish storage directories must not be symbolic links.");
+        }
+        if (!stats.isDirectory()) {
+            throw new Error("ENOTDIR: humanish storage path must be a directory.");
+        }
+    }
+    return current;
+}
+function assertSafeStorageSegments(segments) {
+    if (!segments.every(isSafeStorageSegment)) {
+        throw new Error("humanish storage paths must use non-empty path segments.");
+    }
+}
+function isSafeStorageSegment(segment) {
+    return (segment.length > 0 &&
+        segment !== "." &&
+        segment !== ".." &&
+        !segment.includes("/") &&
+        !segment.includes("\\") &&
+        !segment.includes("\0"));
+}
+/** Missing is fine; anything present must be a single-link regular file. */
+export async function assertRegularFileOrMissing(filePath, subject = "humanish storage files") {
+    try {
+        const stats = await lstat(filePath);
+        if (stats.isSymbolicLink() || !stats.isFile() || stats.nlink > 1) {
+            throw new Error(`${subject} must be single-link regular files, not symbolic links or hardlinks.`);
+        }
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return;
+        }
+        throw error;
+    }
+}
+async function assertNoSymlinkDescendants(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    for (const entry of entries) {
+        const child = path.join(directory, entry.name);
+        // A run directory can be written CONCURRENTLY with this walk — the atomic writer creates a
+        // `.humanish-write-*.tmp` sibling and renames it, and a run now also refreshes its own status
+        // record on a cadence. An entry that vanished between readdir and lstat therefore proves
+        // nothing except that it is gone, and a path that no longer exists cannot be a symlink escape:
+        // skip it rather than failing the containment check on a benign race.
+        let stats;
+        try {
+            stats = await lstat(child);
+        }
+        catch (error) {
+            if (isNodeError(error) && error.code === "ENOENT") {
+                continue;
+            }
+            throw error;
+        }
+        if (stats.isSymbolicLink()) {
+            throw new Error("humanish run directories must not contain symbolic links.");
+        }
+        if (stats.isDirectory()) {
+            await assertNoSymlinkDescendants(child);
+        }
+        else if (!stats.isFile() || stats.nlink > 1) {
+            throw new Error("humanish run leaves must be single-link regular files, not hardlinks or special files.");
+        }
+    }
+}
+async function capturePreparedRunArtifactPaths(paths, runRoot) {
+    const physicalRunRoot = await realpath(runRoot);
+    const physicalRunsRoot = await realpath(path.dirname(runRoot));
+    const [runStats, runsStats] = await Promise.all([
+        lstat(physicalRunRoot, { bigint: true }),
+        lstat(physicalRunsRoot, { bigint: true }),
+    ]);
+    if (!runStats.isDirectory() ||
+        runStats.isSymbolicLink() ||
+        !runsStats.isDirectory() ||
+        runsStats.isSymbolicLink()) {
+        throw new Error("Prepared humanish run storage must use physical directories.");
+    }
+    return Object.freeze({
+        ...paths,
+        physicalLatestPointer: path.join(physicalRunsRoot, "latest.json"),
+        physicalRunRoot,
+        physicalRunsRoot,
+        runRootIdentity: Object.freeze({
+            birthtimeNs: runStats.birthtimeNs,
+            dev: runStats.dev,
+            ino: runStats.ino,
+        }),
+        runsRootIdentity: Object.freeze({
+            birthtimeNs: runsStats.birthtimeNs,
+            dev: runsStats.dev,
+            ino: runsStats.ino,
+        }),
+    });
+}
+/** The directory is still the physical, non-symlink directory captured as `identity`. */
+export async function assertDirectoryIdentity(directory, identity, changedMessage = "Prepared humanish run storage identity changed.") {
+    const stats = await lstat(directory, { bigint: true });
+    if (stats.isSymbolicLink() ||
+        !stats.isDirectory() ||
+        stats.birthtimeNs !== identity.birthtimeNs ||
+        stats.dev !== identity.dev ||
+        stats.ino !== identity.ino ||
+        (await realpath(directory)) !== directory) {
+        throw new Error(changedMessage);
+    }
+}
+const riskyPublicArtifactPathSegments = new Set([
+    ".git",
+    "Cookies",
+    "Login Data",
+    "Local Storage",
+    "Preferences",
+    "Secure Preferences",
+    "profiles",
+]);
+export function isRiskyPublicArtifactPath(relativePath) {
+    return relativePath
+        .split(/[\\/]/)
+        .some((segment) => riskyPublicArtifactPathSegments.has(segment));
+}
+export function isLocalEvidenceArtifactPath(value) {
+    const normalized = value.replace(/\\/g, "/");
+    return (value.length > 0 &&
+        !/^\[[a-z0-9._-]+\]$/i.test(normalized) &&
+        !path.isAbsolute(normalized) &&
+        !normalized.includes("://") &&
+        !normalized.startsWith("..") &&
+        !normalized.split("/").includes("..") &&
+        !isRiskyPublicArtifactPath(normalized));
+}

package/dist/run/preflight-receipts.d.ts

@@ -0,0 +1,46 @@
+import { type PreparedSelectedOutputDirectory } from "./contained-output.js";
+/**
+ * Who opened a journal. A pid means nothing outside its host and pid namespace (a probe in a
+ * container writing to a bind-mounted checkout has a pid the host cannot see), so reclaim trusts
+ * a dead pid only when both match its own.
+ */
+interface PreflightOwner {
+    hostname: string;
+    /** `pid:[inode]` from /proc/self/ns/pid, where the platform has one. */
+    pidNamespace?: string;
+    pid: number;
+    /** Start time in clock ticks since boot (/proc/<pid>/stat), which tells a reused pid apart. */
+    startTicks?: string;
+    createdAt: string;
+    /** The probe's server-side timeout. */
+    leaseMs: number;
+}
+export interface PreflightJournal {
+    id: string;
+    root: PreparedSelectedOutputDirectory;
+    /** Absent when the owner record is missing or unreadable. */
+    owner?: PreflightOwner;
+}
+/** Create this process's journal directory for one probe with the given lease. */
+export declare function openPreflightJournal(cwd: string, leaseMs: number): Promise<PreflightJournal>;
+/** Every probe journal left under .humanish/preflight, oldest first. */
+export declare function listPreflightJournals(cwd: string): Promise<PreflightJournal[]>;
+/** Hand a journal over to reclaim: its probe finished without confirming the kill. */
+export declare function abandonPreflightJournal(journal: PreflightJournal): Promise<void>;
+/**
+ * Whether reclaim may kill a journal's sandboxes: the journal was abandoned, its lease has fully
+ * elapsed, or its owner ran in this host and pid namespace and is gone (or its pid now belongs to
+ * another process). Anything else may be a live probe, and the reason says why it was left.
+ */
+export declare function preflightReclaimDecision(journal: PreflightJournal, nowMs: number): Promise<{
+    reclaim: true;
+} | {
+    reclaim: false;
+    reason: string;
+}>;
+/**
+ * Remove a journal whose sandbox is confirmed gone. Only the files humanish writes there and the
+ * named files are removed; a directory holding anything else stays.
+ */
+export declare function discardPreflightJournal(journal: PreflightJournal, alsoRemove?: readonly string[]): Promise<void>;
+export {};