humanish 0.104.3 → 0.106.0

package/dist/lab/preflight-probes.js

@@ -0,0 +1,312 @@
+// The two reachability probes `humanish lab preflight` can run: public-preview checks a public
+// target from an E2B desktop, and sandbox-loopback serves a clone subject inside one. Each leases one
+// sandbox, journals it for `humanish reclaim --preflight`, and tears it down. preflight.ts resolves
+// the lab and dispatches here.
+import { cloneProvisioningBudgetMs, provisionCloneSubject } from "../subject/clone.js";
+import { CUA_ACTOR_LAB_PROVIDER_METADATA } from "../routes/computer-use/e2b-desktop/prepare.js";
+import { MAX_SANDBOX_MS } from "../substrates/e2b/lifetime.js";
+import { abandonPreflightJournal, discardPreflightJournal, openPreflightJournal, } from "../run/preflight-receipts.js";
+import { probeUrl } from "../substrates/detached.js";
+import { loadE2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { acquireE2BDesktopSandbox, readE2BRelease } from "../substrates/e2b/sandbox.js";
+import { e2bShell } from "../substrates/e2b/shell.js";
+import { redactText } from "../evidence/redaction.js";
+import { digest, fail, finalize } from "./preflight-result.js";
+import { rosterOf } from "./parse/actors.js";
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+// Room on the probe's lease for desktop boot and teardown around the work it does.
+const PREFLIGHT_LEASE_BUFFER_MS = 5 * 60_000;
+export async function runPublicPreviewPreflight(ctx) {
+    const routeError = publicPreviewRouteError(ctx.config, ctx.route);
+    if (routeError) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+            { name: "route", ok: false, message: routeError },
+        ]);
+    }
+    const rosterTargets = ctx.targets.filter((target) => target.kind === "actors[0].lanes[].target");
+    const publicTargets = rosterTargets.length > 0
+        ? rosterTargets
+        : ctx.targets.filter((target) => target.kind === "subject.appUrl");
+    if (publicTargets.length === 0) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview preflight needs at least one declared app-url target.", [{ name: "targets", ok: false, message: "no app-url targets were declared" }]);
+    }
+    const loopbackTarget = publicTargets.find((target) => target.loopback);
+    if (loopbackTarget) {
+        blockTarget(loopbackTarget, "public-preview requires externally reachable non-loopback targets.");
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY", "public-preview reachability cannot prove loopback targets from a hosted desktop; use sandbox-loopback or a prepared public target.", [
+            {
+                name: "target policy",
+                ok: false,
+                message: "loopback target blocked before sandbox launch",
+            },
+        ]);
+    }
+    const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
+    if (!e2bApiKey) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "public-preview preflight creates one E2B desktop to probe target reachability; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+    }
+    // Each target gets at most one readiness budget.
+    const leaseMs = publicTargets.length * ctx.timeoutMs + PREFLIGHT_LEASE_BUFFER_MS;
+    const probe = await withPreflightSandbox(ctx, { e2bApiKey, leaseMs }, async (shell) => {
+        for (const target of publicTargets) {
+            const reachable = await probeUrl(shell, targetUrlFor(ctx.config, target), {
+                timeoutMs: ctx.timeoutMs,
+                requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+                ...(ctx.hooks.now === undefined ? {} : { now: ctx.hooks.now }),
+                ...(ctx.hooks.sleep === undefined ? {} : { sleep: ctx.hooks.sleep }),
+            });
+            markTargetReachability(target, reachable);
+        }
+    });
+    if (!probe.ok) {
+        return probe.result;
+    }
+    const failed = publicTargets.find((target) => target.reachable === false);
+    if (failed) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE", "one or more declared public-preview targets were not reachable from the hosted desktop.", [
+            {
+                name: "target reachability",
+                ok: false,
+                message: `${publicTargets.filter((target) => target.reachable).length}/${publicTargets.length} targets reachable`,
+            },
+        ]);
+    }
+    return finalize(ctx, {
+        check: {
+            name: "target reachability",
+            ok: true,
+            message: `${publicTargets.length}/${publicTargets.length} targets reachable from hosted desktop`,
+        },
+    });
+}
+export async function runSandboxLoopbackPreflight(ctx) {
+    const routeError = sandboxLoopbackRouteError(ctx.config, ctx.route);
+    if (routeError) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", routeError, [
+            { name: "route", ok: false, message: routeError },
+        ]);
+    }
+    const missingEnv = (ctx.config.subject.env ?? []).filter((name) => !ctx.env[name]?.trim());
+    if (missingEnv.length > 0) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_ENV_MISSING", `sandbox-loopback preflight needs declared env values: ${missingEnv.join(", ")}`, [
+            {
+                name: "subject env",
+                ok: false,
+                message: `${missingEnv.length} declared env var value(s) missing`,
+            },
+        ]);
+    }
+    const e2bApiKey = ctx.env.E2B_API_KEY?.trim();
+    if (!e2bApiKey) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED", "sandbox-loopback preflight creates one E2B desktop to clone, serve, and probe the subject; E2B_API_KEY is required.", [{ name: "e2b api key", ok: false, message: "missing E2B_API_KEY" }]);
+    }
+    const repo = ctx.config.subject.repos?.[0];
+    const serve = ctx.config.subject.serve;
+    if (!repo || !serve) {
+        return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "sandbox-loopback preflight requires one clone repo and subject.serve.", [{ name: "clone subject", ok: false, message: "missing repo or serve block" }]);
+    }
+    let subjectCommitDigest;
+    // The longest the clone and serve steps can take with the lab's own budgets, so the probe is
+    // never cut off where the run's provisioning would still be allowed to finish.
+    const leaseMs = cloneProvisioningBudgetMs(serve, ctx.config.subject.state) + PREFLIGHT_LEASE_BUFFER_MS;
+    const probe = await withPreflightSandbox(ctx, { e2bApiKey, leaseMs }, async (shell) => {
+        const subjectEnvNames = ctx.config.subject.env ?? [];
+        await provisionCloneSubject(shell, {
+            repo,
+            depth: ctx.config.subject.clone?.depth ?? 1,
+            serve,
+            ...(ctx.config.subject.state === undefined ? {} : { state: ctx.config.subject.state }),
+            hasGithubToken: subjectEnvNames.includes("GITHUB_TOKEN"),
+            requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+            scrub: makeEnvScrubber(ctx.env, subjectEnvNames),
+            onCommit: (commit) => {
+                subjectCommitDigest = digest(commit);
+            },
+            ...(ctx.hooks.now === undefined ? {} : { now: ctx.hooks.now }),
+            ...(ctx.hooks.sleep === undefined ? {} : { sleep: ctx.hooks.sleep }),
+        });
+        const serveTarget = ctx.targets.find((target) => target.kind === "subject.serve.url");
+        if (serveTarget) {
+            markTargetReachability(serveTarget, true);
+        }
+    });
+    if (!probe.ok) {
+        return probe.result;
+    }
+    return finalize(ctx, {
+        check: {
+            name: "subject provisioning",
+            ok: true,
+            message: `clone subject served and answered readiness${subjectCommitDigest ? ` (commit digest ${subjectCommitDigest})` : ""}`,
+        },
+    });
+}
+async function withPreflightSandbox(ctx, args, callback) {
+    let allocation;
+    let failureMessage;
+    // The lease is sized to the probe's work, never longer than a declared sandbox timeout (the run
+    // gets no more than that either) or E2B's maximum.
+    const timeoutMs = Math.min(args.leaseMs, ctx.config.execution?.desktop?.sandboxTimeoutMs ?? MAX_SANDBOX_MS);
+    // The receipt goes to a journal under .humanish/preflight, so `humanish reclaim --preflight`
+    // can kill the probe if this process dies before the finally block does.
+    let journal;
+    try {
+        journal = await openPreflightJournal(ctx.cwd, timeoutMs);
+    }
+    catch (error) {
+        ctx.warnings.push(`Preflight receipt journal could not be created (${compactError(error)}); if this process dies, only the probe's ${timeoutMs} ms timeout ends its sandbox.`);
+    }
+    let acquired = false;
+    try {
+        const module = await (ctx.hooks.loadDesktopModule ?? loadE2BDesktopModule)();
+        const probe = await acquireE2BDesktopSandbox({
+            module,
+            options: {
+                apiKey: args.e2bApiKey,
+                requestTimeoutMs: DEFAULT_REQUEST_TIMEOUT_MS,
+                timeoutMs,
+                lifecycle: { onTimeout: "kill" },
+                metadata: {
+                    ...CUA_ACTOR_LAB_PROVIDER_METADATA,
+                    mode: "lab-preflight",
+                    labId: ctx.config.id,
+                    reachability: ctx.reachability,
+                },
+                ...(ctx.config.subject.env?.length
+                    ? {
+                        envs: Object.fromEntries(ctx.config.subject.env.map((name) => [name, ctx.env[name]])),
+                    }
+                    : {}),
+                ...(ctx.config.execution?.desktop?.resolution
+                    ? { resolution: ctx.config.execution.desktop.resolution }
+                    : {}),
+                dpi: 96,
+            },
+            template: ctx.config.execution?.desktop?.template,
+            receipt: journal === undefined ? null : { root: journal.root, participantId: journal.id },
+        });
+        acquired = true;
+        allocation = probe.allocation;
+        const sandboxId = probe.allocation.resourceId;
+        ctx.sandbox = {
+            created: true,
+            timeoutMs,
+            sandboxIdDigest: digest(sandboxId),
+            ...(ctx.config.execution?.desktop?.template
+                ? { template: ctx.config.execution.desktop.template }
+                : {}),
+        };
+        await callback(e2bShell(probe.sandbox));
+    }
+    catch (error) {
+        failureMessage = compactError(error);
+    }
+    finally {
+        if (allocation !== undefined) {
+            const reading = readE2BRelease(await allocation.close(), {
+                label: "Sandbox",
+                scrub: (text) => text,
+            });
+            ctx.sandbox = { ...ctx.sandbox, killed: reading.released };
+            if (reading.warning)
+                ctx.warnings.push(reading.warning);
+        }
+        await settlePreflightJournal(ctx, journal, !acquired || ctx.sandbox.killed === true);
+    }
+    if (failureMessage) {
+        return {
+            ok: false,
+            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED", failureMessage, [
+                { name: "sandbox preflight", ok: false, message: failureMessage },
+            ]),
+        };
+    }
+    if (ctx.sandbox.created && ctx.sandbox.killed !== true) {
+        return {
+            ok: false,
+            result: fail(ctx, "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED", "preflight sandbox was created but teardown could not be proven.", [{ name: "sandbox teardown", ok: false, message: "sandbox kill was not proven" }]),
+        };
+    }
+    return { ok: true };
+}
+/**
+ * Remove the journal once no sandbox can be left: acquisition failed before a handle came back
+ * (the sandbox module releases what it created), or the kill was confirmed. Otherwise keep it
+ * for `humanish reclaim --preflight`.
+ */
+async function settlePreflightJournal(ctx, journal, gone) {
+    if (journal === undefined)
+        return;
+    if (!gone) {
+        await abandonPreflightJournal(journal).catch(() => undefined);
+        ctx.warnings.push(`The preflight sandbox's receipt stays in .humanish/preflight/${journal.id}; run \`humanish reclaim --preflight\` to kill it by id.`);
+        return;
+    }
+    await discardPreflightJournal(journal).catch((error) => {
+        ctx.warnings.push(`Preflight receipt journal ${journal.id} could not be removed: ${compactError(error)}`);
+    });
+}
+function markTargetReachability(target, reachable) {
+    target.checked = true;
+    target.reachable = reachable;
+    target.status = reachable ? "passed" : "failed";
+    if (reachable) {
+        target.message = "target reachable from preflight substrate";
+        return;
+    }
+    target.errorCode = "HUMANISH_PREFLIGHT_TARGET_UNREACHABLE";
+    target.message = "target did not answer from preflight substrate within the timeout";
+}
+function blockTarget(target, message) {
+    target.checked = false;
+    target.reachable = false;
+    target.status = "blocked";
+    target.errorCode = "HUMANISH_PREFLIGHT_TARGET_BLOCKED";
+    target.message = message;
+}
+function targetUrlFor(config, target) {
+    if (target.kind === "subject.appUrl" && config.subject.appUrl) {
+        return config.subject.appUrl;
+    }
+    if (target.kind === "actors[0].lanes[].target") {
+        const rosterTarget = rosterOf(config.actors[0])?.find((entry) => entry.target && digest(entry.target) === target.targetDigest)?.target;
+        if (rosterTarget)
+            return rosterTarget;
+    }
+    if (target.kind === "subject.serve.url" && config.subject.serve?.url) {
+        return config.subject.serve.url;
+    }
+    throw new Error(`Internal preflight target lookup failed for ${target.label}.`);
+}
+function publicPreviewRouteError(config, route) {
+    if (route !== "computer-use" ||
+        config.subject.source !== "app-url" ||
+        config.execution?.target !== "e2b-desktop") {
+        return "public-preview preflight supports app-url × e2b-desktop computer-use labs.";
+    }
+    if (config.policies?.allowPublicTargets !== true) {
+        return "public-preview preflight requires policies.allowPublicTargets: true so the owner explicitly declares the public/preview target.";
+    }
+    return null;
+}
+function sandboxLoopbackRouteError(config, route) {
+    if (route !== "computer-use" ||
+        config.subject.source !== "clone" ||
+        config.execution?.target !== "e2b-desktop") {
+        return "sandbox-loopback preflight supports clone × e2b-desktop computer-use labs. (local-tree labs are not preflightable yet: see the local-tree goal doc's out-of-scope list; a dry run of the lab is the current no-spend check.)";
+    }
+    if (!config.subject.serve) {
+        return "sandbox-loopback preflight requires subject.serve.";
+    }
+    return null;
+}
+function makeEnvScrubber(env, names) {
+    const values = names
+        .map((name) => env[name])
+        .filter((value) => typeof value === "string" && value.length > 0);
+    return (text) => values.reduce((current, value) => current.replaceAll(value, "[REDACTED_SECRET]"), text);
+}
+function compactError(error) {
+    const raw = error instanceof Error ? error.message : String(error);
+    return redactText(raw).replace(/\s+/g, " ").trim().slice(0, 500);
+}

package/dist/lab/preflight-result.d.ts

@@ -0,0 +1,7 @@
+import type { LabPreflightCheck, LabPreflightResult, PreflightContext } from "./preflight.js";
+export declare const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+export declare function finalize(ctx: PreflightContext, args?: {
+    check?: LabPreflightCheck;
+}): LabPreflightResult;
+export declare function fail(ctx: PreflightContext, code: NonNullable<LabPreflightResult["error"]>["code"], message: string, checks: LabPreflightCheck[]): LabPreflightResult;
+export declare function digest(value: string): string;

package/dist/lab/preflight-result.js

@@ -0,0 +1,43 @@
+// The preflight result a run returns, built from its context. preflight.ts and the probes in
+// preflight-probes.ts both finish through these, so they live below both.
+import { backendOf } from "./plan.js";
+import { automaticAnalysisBudget } from "../analysis/automatic-config.js";
+import { digestText } from "../evidence/redaction.js";
+export const LAB_PREFLIGHT_SCHEMA = "humanish.lab-preflight-result.v1";
+export function finalize(ctx, args) {
+    const checks = args?.check ? [...ctx.checks, args.check] : ctx.checks;
+    const analysis = automaticAnalysisBudget(ctx.config.review?.analysis, ctx.route);
+    return {
+        schema: LAB_PREFLIGHT_SCHEMA,
+        ...(analysis ? { analysis } : {}),
+        ok: checks.every((check) => check.ok) &&
+            ctx.targets.every((target) => target.status !== "failed" && target.status !== "blocked"),
+        cwd: ctx.cwd,
+        lab: ctx.lab,
+        labId: ctx.labId,
+        origin: ctx.origin,
+        path: ctx.path,
+        backend: backendOf(ctx.route),
+        route: ctx.route,
+        reachability: ctx.reachability,
+        checks,
+        targets: ctx.targets,
+        sandbox: ctx.sandbox,
+        spend: {
+            e2bDesktop: ctx.sandbox.created,
+            model: false,
+        },
+        warnings: ctx.warnings,
+    };
+}
+export function fail(ctx, code, message, checks) {
+    return {
+        ...finalize(ctx),
+        ok: false,
+        checks: [...ctx.checks, ...checks],
+        error: { code, message },
+    };
+}
+export function digest(value) {
+    return digestText(value, 16);
+}

package/dist/lab/preflight.d.ts

@@ -0,0 +1,95 @@
+import type { AutomaticAnalysisBudget } from "../analysis/automatic-config.js";
+import type { E2BDesktopModule } from "../substrates/e2b/sdk.js";
+import { type LabConfig } from "./types.js";
+import { LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
+import type { LabBackend } from "./plan.js";
+import { type LabRoute } from "./plan.js";
+import { type LabResolveFailure } from "./discover.js";
+export type LabPreflightReachabilityMode = "metadata" | "public-preview" | "sandbox-loopback" | "prepared-host";
+export interface LabPreflightCheck {
+    name: string;
+    ok: boolean;
+    message: string;
+}
+export interface LabPreflightTarget {
+    label: string;
+    kind: "subject.appUrl" | "actors[0].lanes[].target" | "subject.serve.url" | "subject.product.publicSurface";
+    targetDigest: string;
+    originDigest?: string;
+    loopback: boolean;
+    checked: boolean;
+    reachable?: boolean;
+    status: "not_checked" | "passed" | "failed" | "blocked";
+    statusCode?: number;
+    errorCode?: "HUMANISH_PREFLIGHT_TARGET_BLOCKED" | "HUMANISH_PREFLIGHT_TARGET_UNREACHABLE";
+    message: string;
+}
+interface LabPreflightSandbox {
+    created: boolean;
+    killed?: boolean;
+    /** The probe's server-side timeout, after which the provider kills it. */
+    timeoutMs?: number;
+    sandboxIdDigest?: string;
+    template?: string;
+}
+interface LabPreflightSpend {
+    e2bDesktop: boolean;
+    model: false;
+}
+export interface LabPreflightResult {
+    /** The separate budget for a future live run, never spend by preflight itself. */
+    analysis?: AutomaticAnalysisBudget;
+    schema: typeof LAB_PREFLIGHT_SCHEMA;
+    ok: boolean;
+    cwd: string;
+    lab: string;
+    labId?: string;
+    origin?: string;
+    path?: string;
+    /** The route's older name; `route` is the current one. */
+    backend?: LabBackend;
+    route?: LabRoute;
+    reachability: LabPreflightReachabilityMode;
+    checks: LabPreflightCheck[];
+    targets: LabPreflightTarget[];
+    sandbox: LabPreflightSandbox;
+    spend: LabPreflightSpend;
+    warnings: string[];
+    error?: {
+        code: LabResolveFailure["error"]["code"] | "HUMANISH_LAB_PREFLIGHT_INVALID_OPTION" | "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE" | "HUMANISH_LAB_PREFLIGHT_TARGET_POLICY" | "HUMANISH_LAB_PREFLIGHT_ENV_MISSING" | "HUMANISH_LAB_PREFLIGHT_E2B_REQUIRED" | "HUMANISH_LAB_PREFLIGHT_TARGET_UNREACHABLE" | "HUMANISH_LAB_PREFLIGHT_PROVISION_FAILED" | "HUMANISH_LAB_PREFLIGHT_TEARDOWN_FAILED";
+        message: string;
+    };
+}
+interface LabPreflightHooks {
+    loadDesktopModule?: () => Promise<E2BDesktopModule>;
+    now?: () => number;
+    sleep?: (ms: number) => Promise<void>;
+}
+export interface RunLabPreflightOptions {
+    cwd: string;
+    lab: string;
+    reachability?: LabPreflightReachabilityMode;
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    hooks?: LabPreflightHooks;
+}
+/** A preflight run's state; the probes in preflight-probes.ts read and extend it. */
+export interface PreflightContext {
+    cwd: string;
+    lab: string;
+    labId: string;
+    origin: string;
+    path: string;
+    config: LabConfig;
+    route: LabRoute;
+    reachability: LabPreflightReachabilityMode;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+    hooks: LabPreflightHooks;
+    checks: LabPreflightCheck[];
+    targets: LabPreflightTarget[];
+    sandbox: LabPreflightSandbox;
+    warnings: string[];
+}
+export declare function runLabPreflight(options: RunLabPreflightOptions): Promise<LabPreflightResult>;
+export {};

package/dist/lab/preflight.js

@@ -0,0 +1,117 @@
+import path from "node:path";
+import { isLoopbackUrl } from "./parse/subject.js";
+import {} from "./types.js";
+import { runPublicPreviewPreflight, runSandboxLoopbackPreflight } from "./preflight-probes.js";
+import { digest, fail, finalize, LAB_PREFLIGHT_SCHEMA } from "./preflight-result.js";
+import { routeOf } from "./plan.js";
+import { resolveLabManifest } from "./discover.js";
+import { rosterOf } from "./parse/actors.js";
+const DEFAULT_PREFLIGHT_TIMEOUT_MS = 30_000;
+export async function runLabPreflight(options) {
+    const cwd = path.resolve(options.cwd);
+    const reachability = options.reachability ?? "metadata";
+    const timeoutMs = options.timeoutMs ?? DEFAULT_PREFLIGHT_TIMEOUT_MS;
+    const resolved = await resolveLabManifest(cwd, options.lab);
+    if (!resolved.ok) {
+        return {
+            schema: LAB_PREFLIGHT_SCHEMA,
+            ok: false,
+            cwd,
+            lab: options.lab,
+            reachability,
+            checks: [
+                {
+                    name: "lab manifest",
+                    ok: false,
+                    message: resolved.error.message,
+                },
+            ],
+            targets: [],
+            sandbox: { created: false },
+            spend: { e2bDesktop: false, model: false },
+            warnings: resolved.warnings,
+            error: resolved.error,
+        };
+    }
+    const route = routeOf(resolved.config);
+    const ctx = {
+        cwd,
+        lab: options.lab,
+        labId: resolved.config.id,
+        origin: resolved.origin,
+        path: resolved.path,
+        config: resolved.config,
+        route,
+        reachability,
+        timeoutMs,
+        env: options.env ?? process.env,
+        hooks: options.hooks ?? {},
+        checks: [
+            { name: "lab manifest", ok: true, message: `resolved ${resolved.origin} lab manifest` },
+            { name: "backend", ok: true, message: `selected the ${route} route` },
+        ],
+        targets: collectTargets(resolved.config),
+        sandbox: { created: false },
+        warnings: resolved.warnings,
+    };
+    switch (reachability) {
+        case "metadata":
+            return finalize(ctx, {
+                check: {
+                    name: "reachability",
+                    ok: true,
+                    message: "metadata-only; no network, sandbox, or model calls. Credentials, local login, dependencies and target reachability were not checked; use humanish doctor --lab <lab> for setup checks.",
+                },
+            });
+        case "public-preview":
+            return await runPublicPreviewPreflight(ctx);
+        case "sandbox-loopback":
+            return await runSandboxLoopbackPreflight(ctx);
+        case "prepared-host":
+            return fail(ctx, "HUMANISH_LAB_PREFLIGHT_UNSUPPORTED_ROUTE", "prepared-host preflight requires a library adapter hook; the plain CLI can validate metadata only for this mode.", [
+                {
+                    name: "prepared-host",
+                    ok: false,
+                    message: "no generic CLI hook exists for adopter-prepared hosts yet",
+                },
+            ]);
+    }
+}
+function collectTargets(config) {
+    const targets = [];
+    if (config.subject.appUrl) {
+        targets.push(makeTarget("subject.appUrl", "subject.appUrl", config.subject.appUrl));
+    }
+    for (const [index, entry] of (rosterOf(config.actors[0]) ?? []).entries()) {
+        if (entry.target) {
+            targets.push(makeTarget(`actors[0].lanes[${index}].target`, "actors[0].lanes[].target", entry.target));
+        }
+    }
+    if (config.subject.serve?.url) {
+        targets.push(makeTarget("subject.serve.url", "subject.serve.url", config.subject.serve.url));
+    }
+    for (const [index, surface] of (config.subject.product?.publicSurfaces ?? []).entries()) {
+        targets.push(makeTarget(`subject.product.publicSurfaces[${index}]`, "subject.product.publicSurface", surface));
+    }
+    return targets;
+}
+function makeTarget(label, kind, url) {
+    return {
+        label,
+        kind,
+        targetDigest: digest(url),
+        ...originDigest(url),
+        loopback: isLoopbackUrl(url),
+        checked: false,
+        status: "not_checked",
+        message: "target declared; reachability not checked",
+    };
+}
+function originDigest(value) {
+    try {
+        return { originDigest: digest(new URL(value).origin) };
+    }
+    catch {
+        return {};
+    }
+}

package/dist/lab/route-inputs.d.ts

@@ -0,0 +1,17 @@
+import type { RunLabOptions } from "../run-lab.js";
+import type { ComputerUseRunInput } from "../routes/computer-use/types.js";
+import type { ScriptedRunInput } from "../routes/scripted/types.js";
+import type { SharedWorldRunInput } from "../routes/shared-world/types.js";
+import type { TerminalRunInput } from "../routes/terminal/types.js";
+export declare function computerUseInput(options: RunLabOptions): ComputerUseRunInput;
+export declare function scriptedInput(options: RunLabOptions): ScriptedRunInput;
+export declare function terminalInput(options: RunLabOptions): TerminalRunInput;
+export declare function sharedWorldInput(options: RunLabOptions): SharedWorldRunInput;
+/** A scorer the CLI loads after the route's local checks, and the provenance it stamps on the run. */
+export type LateScorer = Pick<RunLabOptions, "scorer" | "scorerProvenance">;
+/** The computer-use input with a scorer loaded after admission (see withLateScorer). */
+export declare function computerUseInputWithScorer(input: ComputerUseRunInput, late: LateScorer | undefined): ComputerUseRunInput;
+/** The shared-world input with a scorer loaded after admission (see withLateScorer). */
+export declare function sharedWorldInputWithScorer(input: SharedWorldRunInput, late: LateScorer | undefined): SharedWorldRunInput;
+/** The terminal input with a scorer loaded after admission. Terminal runs take no deriveArtifacts. */
+export declare function terminalInputWithScorer(input: TerminalRunInput, late: LateScorer | undefined): TerminalRunInput;