humanish 0.105.0 → 0.106.1

package/dist/run-lab.d.ts

@@ -0,0 +1,110 @@
+import type { AutomaticAnalysisHooks } from "./analysis/automatic-completion.js";
+import { type LateScorer } from "./lab/route-inputs.js";
+import { type LabBackend, type LabRoute } from "./lab/plan.js";
+import { type RunLabDriving, type RunLabHomes } from "./lab/run-lab-options.js";
+import { type LabConfig } from "./lab/types.js";
+import type { ObserverResult } from "./observer/render.js";
+import { type CuaActorLabHooks, type CuaActorLabResult } from "./routes/computer-use/types.js";
+import { type ScriptedBrowserLabHooks, type ScriptedBrowserLabResult } from "./routes/scripted/types.js";
+import { type ConcurrentSharedWorldLabResult, type SharedWorldLabHooks } from "./routes/shared-world/types.js";
+import { type TerminalProductLabHooks, type TerminalProductLabResult } from "./routes/terminal/types.js";
+import { type RunScorerProvenance } from "./run/bundle.js";
+import { type RunResult } from "./run/results.js";
+import { type RunLabProvenance } from "./run/status.js";
+/**
+ * Runs a lab on its route. The options are checked against the route and mapped into the route's
+ * hook bags before anything runs. Each route closes the run it started on every exit through its
+ * own run scope (`src/run/run.ts`).
+ */
+export declare function runLab(config: LabConfig, options: RunLabOptions): Promise<LabOutcome>;
+/** A lab planned once: the route's refusal, or the run of its plan. */
+export type PreparedLab = {
+    readonly ok: false;
+    readonly outcome: LabOutcome;
+} | {
+    readonly ok: true;
+    /** Runs the plan. A scorer loaded after planning joins the run's hooks; it changes no plan. */
+    run(scorer?: LateScorer): Promise<LabOutcome>;
+};
+/**
+ * Normalizes the options and plans the lab once, so a caller can present a refusal before it loads
+ * anything the run needs. A local browser study's desktop lane and provider are bound first, so the
+ * plan is made with them; with createDesktopLane the caller provides the desktop, and with
+ * buildExecutor it drives the app in process and needs none.
+ */
+export declare function prepareLab(config: LabConfig, options: RunLabOptions): Promise<PreparedLab>;
+/**
+ * Runtime overrides from CLI flags, the typed homes (`RunLabHomes`, `RunLabDriving`) and the older
+ * route hook bags they replace. Each wins over the config when provided.
+ */
+export type RunLabOptions = RunLabBase & RunLabHomes & RunLabDriving;
+interface RunLabBase {
+    automaticAnalysis?: AutomaticAnalysisHooks;
+    cwd: string;
+    runId?: string;
+    /** Which manifest this run came from (#455): threaded to the route so the run's own
+     *  status record and bundle can say which lab produced it. Absent for library callers who
+     *  hand a LabConfig directly — the run is then honestly lab-less rather than guessed. */
+    lab?: RunLabProvenance;
+    dryRun?: boolean;
+    open?: boolean;
+    /** Participant count override: preview participants or computer-use desktops. */
+    count?: number;
+    /** CUA fan-out only: create a new run for failed/selected lanes from a prior run. */
+    rerun?: {
+        sourceRunId: string;
+        participantIds?: string[];
+        /** @deprecated The older name of `participantIds`. */
+        laneIds?: string[];
+    };
+    onObserverReady?: (observer: ObserverResult & {
+        ok: true;
+    }) => Promise<void> | void;
+    /** Computer-use route hooks: subject provisioning (library callers) + test DI seams. */
+    cuaHooks?: CuaActorLabHooks;
+    /** Scripted-browser route hooks: browser injection + test DI seams (mirror of cuaHooks). */
+    scriptedHooks?: ScriptedBrowserLabHooks;
+    /** Terminal-product route hooks: sandbox/runtime-auth DI seams (mirror of cuaHooks). */
+    terminalHooks?: TerminalProductLabHooks;
+    /** Shared-world route hooks: sandbox / runSession / checkpoint DI seams (mirror of cuaHooks). */
+    sharedWorldHooks?: SharedWorldLabHooks;
+    /**
+     * CONFIG-DECLARED scorer provenance (#316), forwarded alongside whichever hooks bag carries the
+     * loaded scorer. Its presence is the "declared" marker the terminal route reads to flip a
+     * status:"fail" verdict; the browser routes stamp it as evidence (they already flip). Core-computed
+     * (path + digest), never adopter-supplied; absent for library callers.
+     */
+    scorerProvenance?: RunScorerProvenance;
+}
+/** A run's result and the route it ran on. */
+interface RouteOutcome<R extends LabRoute, B extends LabBackend, T> {
+    route: R;
+    /** @deprecated The route's older name. Use `route`; this field goes in the next minor. */
+    backend: B;
+    result: T;
+}
+export type LabOutcome = RouteOutcome<"preview", "synthetic", RunResult> | RouteOutcome<"computer-use", "cua", CuaActorLabResult> | RouteOutcome<"scripted", "scripted", ScriptedBrowserLabResult> | RouteOutcome<"terminal", "terminal", TerminalProductLabResult> | RouteOutcome<"shared-world", "concurrent-shared-world", ConcurrentSharedWorldLabResult>;
+/**
+ * A plan past its route's local checks that need no scorer: the refusal they returned, or the
+ * route's run, which takes a scorer loaded after them.
+ */
+export type AdmittedPlan<R extends LabRoute = LabRoute> = {
+    readonly ok: false;
+    readonly outcome: Extract<LabOutcome, {
+        route: R;
+    }>;
+} | {
+    readonly ok: true;
+    run(scorer?: LateScorer): Promise<Extract<LabOutcome, {
+        route: R;
+    }>>;
+};
+/** The result of a run on route `R`, the `result` of that route's `LabOutcome`. */
+export type LabResult<R extends LabRoute = LabRoute> = {
+    preview: RunResult;
+    "computer-use": CuaActorLabResult;
+    scripted: ScriptedBrowserLabResult;
+    terminal: TerminalProductLabResult;
+    "shared-world": ConcurrentSharedWorldLabResult;
+}[R];
+export {};

package/dist/run-lab.js

@@ -0,0 +1,148 @@
+// runLab runs one lab. It normalizes the caller's options, binds a local browser study's desktop
+// and provider, and plans the lab once with planLab. A refused plan returns the route's own result
+// envelope before anything starts. One switch on plan.route then calls the route's admit function,
+// which runs the route's local checks that need no scorer (keys, subject env, the local agent) and
+// returns the route's run. prepareLab is the same path in two steps, so the CLI can present either
+// refusal before it loads a declared review scorer.
+import { computerUseInput, scriptedInput, sharedWorldInput, terminalInput, } from "./lab/route-inputs.js";
+import { planLab, resolveLabDryRun, routeOf } from "./lab/plan.js";
+import { normalizeRunLabOptions, optionRefusalOutcome, } from "./lab/run-lab-options.js";
+import {} from "./lab/types.js";
+import { admitComputerUsePlan, computerUseLabRefusal } from "./routes/computer-use/route.js";
+import { participantDesktopOf } from "./routes/computer-use/participant-desktop.js";
+import {} from "./routes/computer-use/types.js";
+import { admitPreviewPlan, previewLabRefusal } from "./routes/preview.js";
+import { admitScriptedPlan, scriptedLabRefusal } from "./routes/scripted/route.js";
+import {} from "./routes/scripted/types.js";
+import { admitSharedWorldPlan, sharedWorldLabRefusal } from "./routes/shared-world/route.js";
+import {} from "./routes/shared-world/types.js";
+import { admitTerminalPlan, terminalLabRefusal } from "./routes/terminal/route.js";
+import {} from "./routes/terminal/types.js";
+import {} from "./run/bundle.js";
+import {} from "./run/results.js";
+import {} from "./run/status.js";
+import { isLocalBrowserLab, localBrowserDefaults } from "./substrates/local/runtime-config.js";
+/**
+ * Runs a lab on its route. The options are checked against the route and mapped into the route's
+ * hook bags before anything runs. Each route closes the run it started on every exit through its
+ * own run scope (`src/run/run.ts`).
+ */
+export async function runLab(config, options) {
+    const prepared = await prepareLab(config, options);
+    return prepared.ok ? prepared.run() : prepared.outcome;
+}
+/**
+ * Normalizes the options and plans the lab once, so a caller can present a refusal before it loads
+ * anything the run needs. A local browser study's desktop lane and provider are bound first, so the
+ * plan is made with them; with createDesktopLane the caller provides the desktop, and with
+ * buildExecutor it drives the app in process and needs none.
+ */
+export async function prepareLab(config, options) {
+    const lab = localBrowserDefaults(config);
+    const route = routeOf(lab);
+    const normalized = normalizeRunLabOptions(lab, route, options);
+    if (!normalized.ok)
+        return { ok: false, outcome: optionRefusalOutcome(lab, route, options, normalized) };
+    const hooks = normalized.options.cuaHooks;
+    const localVm = isLocalBrowserLab(lab) &&
+        (hooks === undefined || participantDesktopOf(hooks) === undefined) &&
+        hooks?.buildExecutor === undefined
+        ? (await import("./routes/computer-use/local-vm.js")).prepareLocalVmStudy
+        : undefined;
+    const study = localVm?.({ ...normalized.options, config: lab });
+    const planning = study?.options ?? normalized.options;
+    const planned = planLab(lab, planning);
+    if (!planned.ok) {
+        await study?.close();
+        const outcome = await refusalOutcome(lab, planning, planned.refusal);
+        outcome.result.warnings.push(...normalized.warnings);
+        return { ok: false, outcome };
+    }
+    const admitted = await admitPlan(lab, planning, planned.planned.plan);
+    if (!admitted.ok) {
+        await study?.close();
+        admitted.outcome.result.warnings.push(...normalized.warnings);
+        return { ok: false, outcome: admitted.outcome };
+    }
+    return {
+        ok: true,
+        async run(scorer) {
+            // The admitted hooks report onEvent failures into normalized.warnings, so every exit from
+            // the run carries that one array.
+            try {
+                if (scorer !== undefined) {
+                    // Checks the scorer against the route and the caller's options, as if passed up front.
+                    // Only its refusal is used; its options and warnings array are not.
+                    const withScorer = normalizeRunLabOptions(lab, route, { ...options, ...scorer });
+                    if (!withScorer.ok) {
+                        const outcome = optionRefusalOutcome(lab, route, options, withScorer);
+                        outcome.result.warnings.push(...normalized.warnings);
+                        return outcome;
+                    }
+                }
+                // The route layers the scorer over the inputs it admitted, and the local study is not
+                // rebuilt for it. The admitted runSession, provider and participant desktop belong to this
+                // study, so a rebuilt one would leave the participants they start for no finally to close.
+                const outcome = await admitted.run(scorer);
+                outcome.result.warnings.push(...normalized.warnings);
+                return outcome;
+            }
+            finally {
+                await study?.close();
+            }
+        },
+    };
+}
+/** The route's admit function for a plan, with the route's input from the run's options. */
+async function admitPlan(config, options, plan) {
+    switch (plan.route) {
+        case "preview":
+            return admitPreviewPlan(plan, options);
+        case "computer-use":
+            return admitComputerUsePlan(plan, computerUseInput(options), config);
+        case "scripted":
+            return admitScriptedPlan(plan, scriptedInput(options));
+        case "terminal":
+            return admitTerminalPlan(plan, terminalInput(options));
+        case "shared-world":
+            return admitSharedWorldPlan(plan, sharedWorldInput(options), config);
+    }
+}
+/** The refused route's own result, with the envelope and analysis record its runner returns. */
+async function refusalOutcome(config, options, refusal) {
+    // Spend-safe default: a lab goes live only when the config (or CLI) says so.
+    const dryRun = resolveLabDryRun(config, options.dryRun, true) ?? true;
+    const lab = options.lab === undefined ? {} : { lab: options.lab };
+    switch (refusal.route) {
+        case "preview":
+            return {
+                route: "preview",
+                backend: "synthetic",
+                result: previewLabRefusal(options.cwd, refusal),
+            };
+        case "computer-use":
+            return {
+                route: "computer-use",
+                backend: "cua",
+                result: await computerUseLabRefusal({ ...computerUseInput(options), ...lab, config, dryRun }, refusal),
+            };
+        case "scripted":
+            return {
+                route: "scripted",
+                backend: "scripted",
+                result: await scriptedLabRefusal({ ...scriptedInput(options), ...lab, config, dryRun }, refusal),
+            };
+        case "terminal":
+            return {
+                route: "terminal",
+                backend: "terminal",
+                result: await terminalLabRefusal({ ...terminalInput(options), ...lab, config, dryRun }, refusal),
+            };
+        case "shared-world":
+            return {
+                route: "shared-world",
+                backend: "concurrent-shared-world",
+                result: await sharedWorldLabRefusal({ ...sharedWorldInput(options), ...lab, config, dryRun }, refusal),
+            };
+    }
+}

package/dist/subject/clone.d.ts

@@ -0,0 +1,37 @@
+import type { LabSubjectServe, LabSubjectState } from "../lab/types.js";
+import type { RunSubjectStateStepRecord } from "../run/bundle.js";
+import { type DetachedTimers } from "../substrates/detached.js";
+import { type Shell } from "../substrates/shell.js";
+import { type SubjectPhaseEvent } from "./steps.js";
+/** The longest provisionCloneSubject can take with the lab's budgets: the clone, then serving. */
+export declare function cloneProvisioningBudgetMs(serve: LabSubjectServe, state: LabSubjectState | undefined): number;
+/**
+ * Provision a clone subject inside the sandbox: clone, then the shared serve pipeline (install,
+ * state before-build, build, state before-start, start, readiness probe, state after-ready).
+ * Returns the latest subject HEAD after successful provisioning. Throws (with a capped log tail
+ * for the caller to redact) on any failing step; the lab persists that as a failed-evidence
+ * bundle.
+ *
+ * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates via an
+ * Authorization header computed in the sandbox from the provisioned env: the token never appears
+ * in the script text, the process argv beyond the transient git call, the clone URL, or
+ * .git/config.
+ */
+export declare function provisionCloneSubject(shell: Shell, args: {
+    repo: string;
+    depth: number;
+    serve: LabSubjectServe;
+    /** Declared subject state (seed steps; external declaration is provenance-only). */
+    state?: LabSubjectState;
+    hasGithubToken: boolean;
+    requestTimeoutMs: number;
+    /** Literal scrubber for known provisioned values, applied to log tails PRE-truncation. */
+    scrub: (text: string) => string;
+    /** Called the moment the cloned commit resolves, so provenance survives later failures. */
+    onCommit?: (commit: string) => void;
+    /** Called the moment each state step finishes (mirrors onCommit), success or failure. */
+    onStateStep?: (record: RunSubjectStateStepRecord) => void;
+    /** Called at each phase boundary (started/completed): clone, install, build, serve start,
+     *  ready, and each subject.state seed-step group. */
+    onPhase?: (event: SubjectPhaseEvent) => void;
+} & DetachedTimers): Promise<string | undefined>;

package/dist/subject/clone.js

@@ -0,0 +1,62 @@
+import { failureTail } from "../evidence/redaction.js";
+import { detachedTimersOf, runDetachedStep } from "../substrates/detached.js";
+import { runOrThrow } from "../substrates/shell.js";
+import { runSubjectServePipeline, serveProvisioningBudgetMs } from "./serve.js";
+import { SOURCE_TIMEOUT_MS, emitPhaseCompleted, emitPhaseStarted, SUBJECT_DIR, } from "./steps.js";
+/** The longest provisionCloneSubject can take with the lab's budgets: the clone, then serving. */
+export function cloneProvisioningBudgetMs(serve, state) {
+    return SOURCE_TIMEOUT_MS + serveProvisioningBudgetMs(serve, state);
+}
+/**
+ * Provision a clone subject inside the sandbox: clone, then the shared serve pipeline (install,
+ * state before-build, build, state before-start, start, readiness probe, state after-ready).
+ * Returns the latest subject HEAD after successful provisioning. Throws (with a capped log tail
+ * for the caller to redact) on any failing step; the lab persists that as a failed-evidence
+ * bundle.
+ *
+ * Auth: when GITHUB_TOKEN is among the declared subject env names, the clone authenticates via an
+ * Authorization header computed in the sandbox from the provisioned env: the token never appears
+ * in the script text, the process argv beyond the transient git call, the clone URL, or
+ * .git/config.
+ */
+export async function provisionCloneSubject(shell, args) {
+    const timers = detachedTimersOf(args);
+    const now = args.now ?? Date.now;
+    let latestCommit;
+    const refreshCommit = async () => {
+        const head = await runOrThrow(shell, `git -C ${SUBJECT_DIR} rev-parse HEAD 2>/dev/null || true`, { requestTimeoutMs: args.requestTimeoutMs });
+        const commit = head.stdout.trim() || undefined;
+        if (commit) {
+            latestCommit = commit;
+            args.onCommit?.(commit);
+        }
+    };
+    const cloneCommand = args.hasGithubToken
+        ? `auth=$(printf 'x-access-token:%s' "$GITHUB_TOKEN" | base64 -w0) && git -c http.extraHeader="Authorization: Basic $auth" clone --depth ${args.depth} https://github.com/${args.repo}.git ${SUBJECT_DIR}`
+        : `git clone --depth ${args.depth} https://github.com/${args.repo}.git ${SUBJECT_DIR}`;
+    const cloneStartedAt = now();
+    emitPhaseStarted(args.onPhase, now, "clone", "cloning subject repository");
+    const clone = await runDetachedStep(shell, {
+        name: "subject-clone",
+        command: cloneCommand,
+        timeoutMs: SOURCE_TIMEOUT_MS,
+        requestTimeoutMs: args.requestTimeoutMs,
+        ...timers,
+    });
+    emitPhaseCompleted(args.onPhase, now, cloneStartedAt, "clone", clone.ok, clone.ok ? "subject repository cloned" : "subject clone failed");
+    if (!clone.ok) {
+        throw new Error(`subject clone ${clone.timedOut ? "timed out" : `failed (exit ${clone.exitCode})`}: ${failureTail(args.scrub(clone.logTail))}`);
+    }
+    await refreshCommit();
+    await runSubjectServePipeline(shell, {
+        serve: args.serve,
+        ...(args.state === undefined ? {} : { state: args.state }),
+        requestTimeoutMs: args.requestTimeoutMs,
+        scrub: args.scrub,
+        ...(args.onStateStep === undefined ? {} : { onStateStep: args.onStateStep }),
+        ...(args.onPhase === undefined ? {} : { onPhase: args.onPhase }),
+        onPhaseComplete: refreshCommit,
+        ...timers,
+    });
+    return latestCommit;
+}

package/dist/subject/desktop-cli.d.ts

@@ -0,0 +1,17 @@
+import type { Shell } from "../substrates/shell.js";
+import { type SubjectPhaseEvent } from "./steps.js";
+/**
+ * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ *
+ * The install runs UNKEYED and before the session starts, for the same reason the clone route
+ * provisions its subject first: what is being studied begins when the participant looks at the
+ * screen. Omitting install deliberately studies product installation; Node/npm remain a
+ * harness prerequisite so the participant can follow the product's public npm instructions.
+ */
+export declare function provisionDesktopCli(shell: Shell, args: {
+    product: string;
+    install?: string;
+    requestTimeoutMs: number;
+    scrub: (value: string) => string;
+    onPhase?: (event: SubjectPhaseEvent) => void;
+}): Promise<void>;

package/dist/subject/desktop-cli.js

@@ -0,0 +1,51 @@
+import { failureTail } from "../evidence/redaction.js";
+import { needsNodeRuntime } from "./runtime.js";
+import { NODE_BOOTSTRAP_COMMAND, NODE_BOOTSTRAP_TIMEOUT_MS } from "./node-bootstrap.js";
+import { runDetachedStep } from "../substrates/detached.js";
+import { emitPhaseCompleted, emitPhaseStarted, INSTALL_TIMEOUT_MS, } from "./steps.js";
+/**
+ * Prepare a CLI study's runtime and, only when declared, its product (#495, #515).
+ *
+ * The install runs UNKEYED and before the session starts, for the same reason the clone route
+ * provisions its subject first: what is being studied begins when the participant looks at the
+ * screen. Omitting install deliberately studies product installation; Node/npm remain a
+ * harness prerequisite so the participant can follow the product's public npm instructions.
+ */
+export async function provisionDesktopCli(shell, args) {
+    const install = args.install;
+    const now = () => Date.now();
+    if (install === undefined || needsNodeRuntime([install])) {
+        const startedAt = now();
+        emitPhaseStarted(args.onPhase, now, "runtime", "providing Node/npm for the desktop CLI study");
+        const bootstrap = await runDetachedStep(shell, {
+            name: "desktop-cli-runtime-node",
+            command: NODE_BOOTSTRAP_COMMAND,
+            cwd: "/home/user",
+            timeoutMs: NODE_BOOTSTRAP_TIMEOUT_MS,
+            requestTimeoutMs: args.requestTimeoutMs,
+        });
+        emitPhaseCompleted(args.onPhase, now, startedAt, "runtime", bootstrap.ok, bootstrap.ok ? "Node runtime ready" : "Node runtime bootstrap failed");
+        if (!bootstrap.ok) {
+            throw new Error(`desktop-cli runtime bootstrap failed for "${args.product}"`);
+        }
+    }
+    if (install === undefined)
+        return;
+    const startedAt = now();
+    emitPhaseStarted(args.onPhase, now, "install", `installing ${args.product} on the desktop`);
+    const result = await runDetachedStep(shell, {
+        name: "desktop-cli-install",
+        command: install,
+        cwd: "/home/user",
+        timeoutMs: INSTALL_TIMEOUT_MS,
+        requestTimeoutMs: args.requestTimeoutMs,
+    });
+    emitPhaseCompleted(args.onPhase, now, startedAt, "install", result.ok, result.ok ? `${args.product} installed` : `installing ${args.product} failed`);
+    if (!result.ok) {
+        // Fail closed: a participant handed a desktop where the product is not installed would produce
+        // a transcript about a missing command, and that finding belongs to the harness, not the tool.
+        // The tail rides along, scrubbed before truncation like every other provisioning failure — a
+        // bare "install failed" is unactionable to whoever wrote the command.
+        throw new Error(args.scrub(`desktop-cli install failed for "${args.product}" (${result.timedOut ? "timed out" : `exit ${result.exitCode ?? "?"}`}): ${failureTail(args.scrub(result.logTail))}`));
+    }
+}

package/dist/subject/local-tree-archive.d.ts

@@ -0,0 +1,82 @@
+export interface LocalTreeEntry {
+    relPath: string;
+    kind: "file" | "symlink";
+    size: number;
+}
+export interface LocalTreeGitInfo {
+    commit: string;
+    dirty: boolean;
+}
+export interface LocalTreeArchive {
+    archivePath: string;
+    /** 64 lowercase hex sha256, the provenance pin (not the repo's 16-char display digest). */
+    archiveSha256: string;
+    fileCount: number;
+    totalBytes: number;
+    /** Absent when root is not a git work tree. */
+    git?: LocalTreeGitInfo;
+}
+export interface CreateLocalTreeArchiveOptions {
+    /** Default: a fresh directory under os.tmpdir(). */
+    outputPath?: string;
+    /** Author-supplied path prefixes / basenames, on top of the always-on denylist. */
+    extraExclude?: string[];
+    /** Upload size cap. Default DEFAULT_LOCAL_TREE_MAX_ARCHIVE_BYTES (256 MiB). */
+    maxArchiveBytes?: number;
+}
+/**
+ * Path segments that are always excluded, wherever they appear in a relPath,
+ * in both git and fallback enumeration modes. Not overridable by callers.
+ */
+export declare const LOCAL_TREE_DENYLIST_PATH_SEGMENTS: readonly [".git", "node_modules", ".humanish", ".homun"];
+/**
+ * Basename glob patterns (single leading or trailing `*` only) that are always
+ * excluded, in both git and fallback enumeration modes. Not overridable by
+ * callers. This is a safety net for secret-shaped files that were never
+ * gitignored; in git mode `.gitignore` already handles the bulk (build output,
+ * caches).
+ */
+export declare const LOCAL_TREE_DENYLIST_BASENAME_PATTERNS: readonly [".env*", "*.pem", "*.key", "*.p12", "*.pfx", "id_rsa*", "id_dsa*", "id_ed25519*", "id_ecdsa*", "*.keystore", "*.jks", "*.ppk", "*.gpg", "*.tfstate", "terraform.tfstate.backup", ".npmrc", ".netrc", ".dockercfg", "kubeconfig", "credentials.json", "service-account.json", "serviceAccount.json", "service_account.json", "secrets.json", "secrets.yaml", "secrets.yml", "auth.json"];
+/** Default upload size cap: 256 MiB. */
+export declare const DEFAULT_LOCAL_TREE_MAX_ARCHIVE_BYTES: number;
+/**
+ * Enumerate the packable entries of a local working tree.
+ *
+ * When root is a git work tree, the list is `git ls-files --cached --others
+ * --exclude-standard -z`: tracked files plus untracked-but-not-ignored files,
+ * honoring .gitignore exactly as git does. Entries that no longer exist on
+ * disk (staged deletes) are dropped, and entries that resolve to a directory
+ * on disk (a nested repo or worktree boundary) are dropped rather than
+ * recursed into.
+ *
+ * Otherwise, a recursive readdir walk applies only the always-on denylist
+ * plus extraExclude; .gitignore semantics require git, so this fallback is
+ * coarser by design.
+ *
+ * The always-on denylist is applied in both modes and is not overridable.
+ * The returned entries are sorted bytewise by relPath.
+ */
+export declare function enumerateLocalTree(root: string, options?: {
+    extraExclude?: string[];
+}): {
+    entries: LocalTreeEntry[];
+    git?: LocalTreeGitInfo;
+};
+/**
+ * Enumerate a local working tree and pack it into a gzipped tar archive,
+ * computing archiveSha256 from the exact same entries list used for the tar
+ * file list.
+ *
+ * Fails closed when: the root is missing or not a directory; enumeration
+ * produces zero entries; or total packed bytes exceed maxArchiveBytes.
+ */
+export declare function createLocalTreeArchive(root: string, options?: CreateLocalTreeArchiveOptions): LocalTreeArchive;
+/**
+ * Normalize an author-supplied exclude entry to the relPath shape enumeration
+ * produces (no leading "./", no trailing "/"). Absolute paths and glob syntax
+ * are REJECTED, not silently no-op'd: an exclude the author believed in but
+ * that never matches anything is a leak vector, so unusable shapes fail
+ * closed at the packing boundary (and, for lab manifests, already at parse
+ * time in src/lab/parse/subject.ts).
+ */
+export declare function normalizeExtraExcludeEntry(entry: string): string;