humanish 0.0.1 → 0.15.1

package/dist/e2b-detached.js

@@ -0,0 +1,130 @@
+// Detached process management for E2B sandboxes — the substrate primitive behind serving a
+// subject app in-sandbox. E2B's foreground `commands.run` deadlines on long-running work, so
+// every consumer of the pattern has historically re-implemented the same workaround. This
+// module lands it once:
+//
+// - Scripts are written via `files.write`, never heredocs — which eliminates the
+//   sentinel-collision bug class (a command line that equals the heredoc terminator) by
+//   construction.
+// - Bounded steps (install/build) run detached with an ATOMICALLY-written status file
+//   (write tmp + mv), polled by short foreground commands; a timeout kills the process
+//   group and surfaces a capped log tail for the caller to redact and persist.
+// - Long-lived steps (a dev/prod server) launch fully detached via `setsid -f`; the sandbox
+//   lifecycle (kill-on-timeout) owns their reclamation.
+// - Readiness is an explicit curl probe against the declared URL.
+//
+// Log tails are returned RAW; callers must pass them through redaction before persisting
+// (build output can echo env values and paths).
+const WORK_ROOT = "/tmp/humanish-subject";
+const DEFAULT_POLL_INTERVAL_MS = 3000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+const LOG_TAIL_BYTES = 8192;
+const NAME_PATTERN = /^[a-z0-9-]+$/;
+function assertName(name) {
+    if (!NAME_PATTERN.test(name)) {
+        throw new Error(`Detached step name must match ${NAME_PATTERN} (got "${name}").`);
+    }
+}
+/** Single-quote a value for safe interpolation into a shell script. */
+function shq(value) {
+    return `'${value.replaceAll("'", "'\\''")}'`;
+}
+function stepDir(name) {
+    return `${WORK_ROOT}/${name}`;
+}
+// The wrapper script: runs the command from its own session (setsid launch makes the script
+// the process-group leader, so `kill -- -PID` reclaims the whole tree), logs everything, and
+// writes the exit code atomically so a poller can never read a half-written status.
+function wrapperScript(name, command, cwd) {
+    const dir = stepDir(name);
+    return [
+        "#!/bin/bash",
+        `mkdir -p ${shq(dir)}`,
+        `echo $$ > ${shq(`${dir}/pid`)}`,
+        cwd === undefined ? ": # no cwd override" : `cd ${shq(cwd)} || { echo 127 > ${shq(`${dir}/status.tmp`)}; mv ${shq(`${dir}/status.tmp`)} ${shq(`${dir}/status`)}; exit 127; }`,
+        `( ${command} ) > ${shq(`${dir}/log.txt`)} 2>&1`,
+        "code=$?",
+        `echo $code > ${shq(`${dir}/status.tmp`)}`,
+        `mv ${shq(`${dir}/status.tmp`)} ${shq(`${dir}/status`)}`,
+        "exit $code",
+        ""
+    ].join("\n");
+}
+async function writeAndLaunch(desktop, name, command, cwd, requestTimeoutMs) {
+    assertName(name);
+    const dir = stepDir(name);
+    const scriptPath = `${dir}/run.sh`;
+    await desktop.commands.run(`mkdir -p ${shq(dir)}`, { requestTimeoutMs });
+    await desktop.files.write(scriptPath, wrapperScript(name, command, cwd));
+    await desktop.commands.run(`chmod +x ${shq(scriptPath)} && setsid -f ${shq(scriptPath)} < /dev/null > /dev/null 2>&1`, { requestTimeoutMs });
+}
+/** Read the capped log tail for a step (raw — caller redacts). */
+export async function readDetachedLog(desktop, name, requestTimeoutMs = DEFAULT_REQUEST_TIMEOUT_MS) {
+    assertName(name);
+    const result = await desktop.commands.run(`tail -c ${LOG_TAIL_BYTES} ${shq(`${stepDir(name)}/log.txt`)} 2>/dev/null || true`, { requestTimeoutMs });
+    return result.stdout ?? "";
+}
+/**
+ * Run a BOUNDED step (install/build) detached, polling its atomic status file until it
+ * exits or the budget runs out. On timeout the process group is killed and the log tail is
+ * still captured so failures stay diagnosable.
+ */
+export async function runDetachedStep(desktop, options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const pollIntervalMs = options.pollIntervalMs ?? DEFAULT_POLL_INTERVAL_MS;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const dir = stepDir(options.name);
+    await writeAndLaunch(desktop, options.name, options.command, options.cwd, requestTimeoutMs);
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        const status = await desktop.commands.run(`cat ${shq(`${dir}/status`)} 2>/dev/null || true`, { requestTimeoutMs });
+        const text = (status.stdout ?? "").trim();
+        if (text.length > 0) {
+            const exitCode = Number.parseInt(text, 10);
+            const logTail = await readDetachedLog(desktop, options.name, requestTimeoutMs);
+            return { ok: exitCode === 0, exitCode, timedOut: false, logTail };
+        }
+        if (now() >= deadline) {
+            // Kill the whole process group (the script is its own session leader via setsid).
+            await desktop.commands
+                .run(`kill -- -$(cat ${shq(`${dir}/pid`)} 2>/dev/null) 2>/dev/null || true`, { requestTimeoutMs })
+                .catch(() => undefined);
+            const logTail = await readDetachedLog(desktop, options.name, requestTimeoutMs);
+            return { ok: false, timedOut: true, logTail };
+        }
+        await sleep(pollIntervalMs);
+    }
+}
+/**
+ * Launch a LONG-LIVED process (the subject's server) fully detached and return immediately.
+ * No status polling: liveness is the caller's readiness probe, and reclamation belongs to
+ * the sandbox lifecycle (create with kill-on-timeout).
+ */
+export async function startDetachedProcess(desktop, options) {
+    await writeAndLaunch(desktop, options.name, options.command, options.cwd, options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+}
+/**
+ * Poll a URL from INSIDE the sandbox until it answers 2xx/3xx or the budget runs out.
+ * Returns true when the subject is ready.
+ */
+export async function probeUrl(desktop, url, options) {
+    const requestTimeoutMs = options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    const intervalMs = options.intervalMs ?? 1500;
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+    const deadline = now() + options.timeoutMs;
+    for (;;) {
+        const result = await desktop.commands
+            .run(`curl -sf -o /dev/null --max-time 5 ${shq(url)} && echo READY || echo WAIT`, { requestTimeoutMs })
+            .catch(() => ({ stdout: "WAIT" }));
+        if ((result.stdout ?? "").includes("READY")) {
+            return true;
+        }
+        if (now() >= deadline) {
+            return false;
+        }
+        await sleep(intervalMs);
+    }
+}
+//# sourceMappingURL=e2b-detached.js.map

package/dist/e2b-detached.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"e2b-detached.js","sourceRoot":"","sources":["../src/e2b-detached.ts"],"names":[],"mappings":"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"}

package/dist/e2b-terminal-lab.d.ts

@@ -0,0 +1,345 @@
+import type { ActorCompletionReason, ActorPersonaRef, ActorStatus, ActorTrace } from "./actor-contract.js";
+import type { LabConfig, LabScenarioCaps } from "./lab-config.js";
+import { type E2BDesktopModule } from "./e2b-desktop-launch.js";
+import { renderObserver, type ObserverResult } from "./observer.js";
+import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate } from "./run.js";
+import { TERMINAL_AGENT_NOT_IMPLEMENTED_CODE } from "./terminal-agent-actor.js";
+/** Provider-neutral metadata constant: the lane's non-secret tag (mirrors CUA_ACTOR_LAB_PROVIDER_METADATA). */
+export declare const TERMINAL_PRODUCT_LAB_PROVIDER_METADATA: {
+    readonly mode: "terminal-product-lab";
+    readonly tool: "humanish";
+};
+export declare const TERMINAL_EVENTS_ARTIFACT = "terminal-events.ndjson";
+export declare const TERMINAL_TRANSCRIPT_ARTIFACT = "terminal-transcript.txt";
+export declare const TERMINAL_LEDGERS_ARTIFACT = "terminal-ledgers.json";
+export declare const TERMINAL_PRODUCT_LAB_SCHEMA = "humanish.terminal-lab-result.v1";
+/**
+ * Library-level hooks: the DI seams that drive the full live path against a fake sandbox + mock
+ * CLI at zero spend. The deterministic merge-gate test wires loadModule (a fake @e2b/desktop
+ * module) + env (the operator key source) + now (an injected clock); the live rung uses none of
+ * them (it loads the real module and reads the real environment).
+ */
+/**
+ * The read-only evidence a thin adapter's scorer/feedback hook sees (the layer-6 extension seam,
+ * issue #154 acceptance #8). It is the FULLY-ASSEMBLED, redacted, verifiable evidence — the live run
+ * bundle, the provider-neutral actor trace, and the persisted ledgers (substrate/command/
+ * interventions/cleanup/cost/no-spend). Every member is an EXPORTED public type, so a thin adapter
+ * types against `import("humanish")` alone — never a deep `src/` import. The adapter reads this
+ * to score the product attempt and derive feedback; it cannot mutate core's evidence (the lane
+ * attaches only the namespaced `RunAdapterScore` it returns + the feedback candidates it derives).
+ */
+export interface TerminalProductScoringContext {
+    /** The assembled live run bundle (already redacted/scrubbed + verifiable). Read-only to the adapter. */
+    bundle: RunBundle;
+    /** The provider-neutral actor trace for the in-sandbox agent session. */
+    trace: ActorTrace;
+    /** The persisted terminal-product ledgers (lifecycle/command/interventions/cleanup/cost/no-spend). */
+    ledgers: TerminalLedgers;
+    /** The studied product name (public-safe). */
+    product: string;
+    /** The lab id (the run's scenario scope). */
+    labId: string;
+    /** The run id (for building namespaced idempotency keys + evidence pointers). */
+    runId: string;
+}
+export interface TerminalProductLabHooks {
+    /** Lazy-load the E2B module (tests inject a fake; default loadE2BDesktopModule). */
+    loadModule?: () => Promise<E2BDesktopModule>;
+    /**
+     * The operator environment the lane reads the runtime key from (and from which it asserts no
+     * banned credential is requested). Defaults to process.env. The runtime key is injected ONLY
+     * into the command-scoped `codex` invocation — NEVER Sandbox.create envs (the credential
+     * boundary); tests plant a fake key here and assert it never reaches metadata/global env/artifacts.
+     */
+    env?: Record<string, string | undefined>;
+    renderObserverFn?: typeof renderObserver;
+    /** Injected clock for deterministic timestamps + wall-clock arithmetic (tests only). */
+    now?: () => number;
+    /**
+     * SLICE-3 DI seam for the cost ledger. The lane has NO real product-spend signal yet (that is the
+     * adapter's job in SLICE 4), so this slice populates only the provider line (from the trace's
+     * tokenUsage when present). This seam lets the deterministic test (and, later, a SLICE-4 adapter)
+     * inject KNOWN spend lines so the fail-closed cap enforcement can be exercised at $0 without a
+     * real billable run. Production callers never pass this — they get the null-discipline default.
+     */
+    costProbe?: (context: {
+        tokenCostUsd?: number;
+    }) => Partial<Record<"product" | "media" | "payment" | "provider", CostLine>> | undefined;
+    /**
+     * THE LAYER-6 EXTENSION SEAM (issue #154 acceptance #8: "product-adapter hooks WITHOUT forking
+     * core"). A thin in-repo/out-of-tree adapter registers a product scorer here. The lane calls it
+     * (when provided) over the fully-assembled evidence and attaches the returned, ADAPTER-NAMESPACED
+     * `RunAdapterScore` to `bundle.adapterScore` WITHOUT core knowing any product noun (the score is
+     * namespaced + its component breakdown rides in `data`). When NO scorer is given, the default
+     * mission-based verdict (`review`) is unchanged. This is the SEAM the adopter's scorecard plugs
+     * into — NOT a built-in product scorer (that lives in the adopter's repo).
+     */
+    score?: (ctx: TerminalProductScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
+    /**
+     * Companion seam: derive product-feedback candidates from the same assembled evidence. The lane
+     * appends the returned candidates to `bundle.feedbackCandidates`. The adapter records its
+     * product-specific concepts (public CLI command observed, hosted success-or-blocker, feedback id,
+     * media/job ids, no-spend proof, defection/friction risk) under each candidate's ADAPTER-NAMESPACED
+     * `adapter` block — never as core enums (issue #154's "record product-specific concepts as
+     * NON-core nouns" list). The candidates must still satisfy core's feedback-candidate shape (which
+     * the bundle verifier enforces), so a malformed adapter candidate fails closed.
+     */
+    deriveFeedback?: (ctx: TerminalProductScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
+}
+export interface RunTerminalProductLabOptions {
+    cwd: string;
+    config: LabConfig;
+    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
+    dryRun: boolean;
+    open?: boolean;
+    runId?: string;
+    hooks?: TerminalProductLabHooks;
+}
+export interface TerminalProductLabResult {
+    schema: typeof TERMINAL_PRODUCT_LAB_SCHEMA;
+    /** True when the bundle verified AND (dry-run, or the live session reached a terminal verdict
+     *  without a harness error + cleanup was proven). The agent's pass/fail is evidence, not the
+     *  lab's exit code. */
+    ok: boolean;
+    cwd: string;
+    labId: string;
+    /** The registry-resolved actor id that ran (or would run) the session. */
+    actor: string;
+    /** The studied product name (public-safe). */
+    product: string;
+    dryRun: boolean;
+    runId: string;
+    /** Live-only: the in-sandbox agent session verdict (omitted on dry-run / pre-session failure). */
+    session?: {
+        status: ActorStatus;
+        completionReason: ActorCompletionReason;
+        reason: string;
+    };
+    /** Live-only: the sandbox lifecycle proof (the key/auth value is NEVER surfaced here). */
+    sandbox?: {
+        sandboxId: string;
+        killed: boolean;
+        /** BY-ID proof (never a re-list): 0 = confirmed reclaimed, 1 = still present (unconfirmed),
+         *  -1 = kill(id) itself failed or was unavailable. See TerminalLedgers["cleanup"]. */
+        remaining: number;
+    };
+    /** Live-only: the spend ledger surfaced on the result (SLICE 3) — unknowns are null, never guessed.
+     *  Lets a programmatic caller read spend without parsing the bundle. */
+    cost?: {
+        knownTotalUsd: number;
+        fullyMeasured: boolean;
+        /** Per-category USD: a known number, or null = NOT MEASURED (never coerced to 0). */
+        lines: Record<"product" | "media" | "payment" | "provider", number | null>;
+    };
+    /** Live-only: the no-spend proof DERIVED from the ledger (SLICE 3). */
+    noSpend?: {
+        satisfied: boolean;
+        maxUsd: number | null;
+        knownZeroLines: string[];
+        unmeasuredLines: string[];
+    };
+    observer?: ObserverResult;
+    warnings: string[];
+    error?: {
+        code: "HUMANISH_TERMINAL_LAB_FAILED" | "HUMANISH_TERMINAL_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_LAB_SUBJECT_INVALID" | "HUMANISH_TERMINAL_LAB_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_LAB_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_MISSING" | "HUMANISH_TERMINAL_LAB_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_LAB_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_LAB_CLEANUP_UNPROVEN" | typeof TERMINAL_AGENT_NOT_IMPLEMENTED_CODE;
+        message: string;
+    };
+}
+export declare function runTerminalProductLab(options: RunTerminalProductLabOptions): Promise<TerminalProductLabResult>;
+/** Substrate lifecycle ledger entry (create/readiness/exec/cleanup events with timestamps). */
+export interface LifecycleRecord {
+    at: string;
+    event: string;
+    /** Redacted+scrubbed before persisting (it never carries a secret, but the harness never trusts that). */
+    message: string;
+}
+/** Command-log ledger entry: which command ran, with what exit/duration (NEVER its env values). */
+export interface CommandLogRecord {
+    at: string;
+    /** A public-safe label for the command (e.g. "codex-exec"); the full argv is bound by digest only. */
+    label: string;
+    /** sha256-12 of the exact command string — pins "same recipe" without persisting it. */
+    commandDigest: string;
+    /** The env var NAMES injected command-scoped (values NEVER persisted) — the credential evidence. */
+    envNames: string[];
+    exitCode?: number;
+    timedOut?: boolean;
+    durationMs: number;
+}
+/**
+ * One operator intervention (assisted-input event). SLICE 2 ships NO assisted-input path, so this
+ * ledger is ALWAYS empty — but always PRESENT (the safety contract: empty-present is the contract,
+ * an absent ledger fails verify). The shape is fixed now so an assisted path (deferred) can fill it.
+ */
+export interface InterventionRecord {
+    at: string;
+    kind: "stdin";
+    /** Redacted+scrubbed digest of the injected input (never the raw bytes). */
+    inputDigest: string;
+}
+/**
+ * One cost line of the spend ledger. THE NULL DISCIPLINE (issue #154, the cost/no-spend asks):
+ * three distinct states are crisply modeled and NEVER conflated —
+ *   - `usd: 0`     => KNOWN to be zero. A measured-and-zero spend (we metered this category and it
+ *                     billed nothing). The no-spend proof may legitimately assert this is zero.
+ *   - `usd: null`  => NOT MEASURED. We carry NO spend signal for this category this slice. `null` is
+ *                     written explicitly (never undefined-omitted, never guessed to 0). The no-spend
+ *                     proof must list this line as UNMEASURED and must NOT claim it is zero.
+ *   - line ABSENT  => NOT APPLICABLE to this lane/run (n/a). The line simply does not appear in
+ *                     `lines`. (This slice always emits all four lines, so absence is reserved for
+ *                     future lanes that genuinely have no such category.)
+ * `null` vs missing-key is the load-bearing distinction: a missing key means "this category does not
+ * exist for this run"; a present key with `null` means "this category exists but we did not measure
+ * it". A no-spend proof that claimed zero on a `null` line would claim more than it measured.
+ */
+export interface CostLine {
+    /** known zero (0) | not measured (null). The key is ALWAYS present when the line is applicable. */
+    usd: number | null;
+    /** Optional billable-unit count, same discipline: a known count, or null = not measured. */
+    count?: number | null;
+    /** How this line's value was established (provenance for the verifier + the human reviewer). */
+    source: "provider-token-usage" | "no-spend-signal" | "operator-cap" | "unmeasured";
+    /** A short, public-safe note (never a secret value). */
+    note: string;
+}
+/** The cost categories the lane meters. product/media/payment are adapter signals (SLICE 4); the
+ *  provider line can be populated this slice from the actor trace's tokenUsage.costUsd when present. */
+export type CostCategory = "product" | "media" | "payment" | "provider";
+/**
+ * The spend ledger (a block of `TerminalLedgers`). The no-spend PROOF is DERIVED from this — never
+ * asserted independently. Every applicable category appears as a line; unknowns are `null`.
+ */
+export interface TerminalCostLedger {
+    schema: "humanish.terminal-cost-ledger.v1";
+    /** USD currency unit (recorded explicitly so a future multi-currency lane is unambiguous). */
+    currency: "usd";
+    lines: Record<CostCategory, CostLine>;
+    /** Sum of the KNOWN (non-null) lines. null lines contribute NOTHING and are NOT guessed as 0. */
+    knownTotalUsd: number;
+    /** True when every applicable line is measured (no null). When false, knownTotalUsd is a LOWER
+     *  bound, not the full spend — the no-spend proof says so honestly. */
+    fullyMeasured: boolean;
+}
+/**
+ * The no-spend proof, DERIVED from the cost ledger (issue #154: "derived from a ledger, not
+ * asserted"). It is honest about what it knows: it lists the KNOWN-zero lines it can vouch for and,
+ * separately, the UNMEASURED (null) lines it CANNOT vouch for. `satisfied` is true only when every
+ * KNOWN line is zero (a known non-zero line fails it); but a proof with unmeasured lines explicitly
+ * says it could not measure them — it never claims zero on a line the ledger marks null.
+ */
+export interface NoSpendProof {
+    schema: "humanish.terminal-no-spend-proof.v1";
+    /** The maxUsd cap this proof was evaluated against (the no-spend scenario declares maxUsd: 0). */
+    maxUsd: number | null;
+    /** True iff every KNOWN (measured) line is <= maxUsd (for a no-spend run, == 0). */
+    satisfied: boolean;
+    /** Categories the ledger MEASURED and found at (known) zero — the proof CAN vouch for these. */
+    knownZeroLines: CostCategory[];
+    /** Categories the ledger measured with a known NON-zero spend (these break `satisfied`). */
+    knownNonZeroLines: CostCategory[];
+    /** Categories the ledger marks `null` (NOT MEASURED). The proof explicitly lists these and does
+     *  NOT claim they are zero — it claims only that it could not measure them this slice. */
+    unmeasuredLines: CostCategory[];
+    /** Sum of the known lines (== 0 for a satisfied no-spend run). */
+    knownTotalUsd: number;
+    /** Human-readable honesty statement covering both what is proven and what is unmeasured. */
+    statement: string;
+}
+/** The persisted terminal-product ledgers artifact (substrate lifecycle + command log + interventions + cleanup + cost). */
+export interface TerminalLedgers {
+    schema: "humanish.terminal-ledgers.v1";
+    lifecycle: LifecycleRecord[];
+    commandLog: CommandLogRecord[];
+    /** ALWAYS present; ALWAYS empty this slice (no assisted-input path) — the safety contract. */
+    interventions: InterventionRecord[];
+    cleanup: {
+        /** True when Sandbox.kill(id) resolved without throwing (either found-and-killed, or a 404
+         *  meaning the exact id was already gone -- both prove absence; see `remaining`/`reason`). */
+        killed: boolean;
+        /** BY-ID proof, NEVER derived from Sandbox.list: 0 = confirmed reclaimed (kill(id) RESOLVED
+         *  -- returned true "found and killed" OR false "404, exact id already gone" -- and, when the
+         *  SDK exposes it, getInfo(id) did not report a live sandbox); 1 = getInfo(id) still reports
+         *  this exact sandbox running/paused (NOT reclaimed); -1 = kill(id) itself failed, threw, or
+         *  was unavailable (the server-side kill-on-timeout is the backstop). */
+        remaining: number;
+        /** Honest, human-readable statement of which by-id signal produced `remaining`. */
+        reason: string;
+    };
+    /** The spend ledger (SLICE 3, additive). Unknowns are `null`, never guessed; the no-spend proof
+     *  below is DERIVED from it. */
+    cost: TerminalCostLedger;
+    /** The no-spend proof DERIVED from `cost` (SLICE 3). Never an independent assertion. */
+    noSpendProof: NoSpendProof;
+}
+/**
+ * Build the sandbox metadata from a POSITIVE ALLOWLIST (safety contract item 6). This is the ONLY
+ * way metadata is set on the terminal lane — it carries solely non-secret labels and rejects any
+ * value that is not a plain short label. A verifier check asserts the persisted metadata has no
+ * prompt/token/secret shapes; this builder makes that true by construction.
+ */
+export declare function buildSandboxMetadata(allowlist: {
+    labId: string;
+    simId: string;
+    runId: string;
+}): Record<string, string>;
+/**
+ * Project the terminal-product lab run into a humanish.run-bundle.v1 (no schema change — a new
+ * producer only). DRY-RUN: a contract bundle. The terminal stream is a contract placeholder
+ * (stdin disabled, no captured tail — honest: nothing ran), the subject is declared UNPINNED, and
+ * the caps/policies/runtime-auth declarations + empty ledgers are recorded so SLICE 2 has a stable
+ * shape to fill. Exported for the bundle-builder tests.
+ */
+export declare function buildTerminalProductBundle(args: {
+    actorId: string;
+    createdAt: string;
+    dryRun: boolean;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    persona: ActorPersonaRef;
+    productName: string;
+    publicSurfaces: string[];
+    caps?: LabScenarioCaps;
+    runtimeAuth?: string;
+    stdin: "disabled" | "planned" | "sent";
+    policies: {
+        allowPrivateRepoAccess: boolean;
+        allowProviderCredentials: boolean;
+        allowPaymentCredentials: boolean;
+        allowGitHubMutation: boolean;
+    };
+    runId: string;
+    source: RunBundle["source"];
+}): RunBundle;
+/**
+ * Build the LIVE terminal-product run bundle (mode "live") from the captured session: the actor
+ * trace seam (stream.actor = trace), the substrate-lifecycle events, the terminal stream with the
+ * redacted transcript tail, and references to the written evidence artifacts (terminal event
+ * stream, transcript, ledgers, actor trace). verifyRun's terminal-product check (gated on
+ * mode==="live") enforces the ledgers + proven cleanup + interventions-present over this bundle.
+ */
+export declare function buildLiveTerminalProductBundle(args: {
+    actorId: string;
+    createdAt: string;
+    labId: string;
+    labTitle?: string;
+    mission: string;
+    persona: ActorPersonaRef;
+    productName: string;
+    publicSurfaces: string[];
+    caps?: LabScenarioCaps;
+    runtimeAuthKeyName: string;
+    policies: {
+        allowPrivateRepoAccess: boolean;
+        allowProviderCredentials: boolean;
+        allowPaymentCredentials: boolean;
+        allowGitHubMutation: boolean;
+    };
+    runId: string;
+    source: RunBundle["source"];
+    trace: ActorTrace;
+    ledgers: TerminalLedgers;
+    sandboxId?: string;
+    sessionError?: string;
+    sessionReason: string;
+}): RunBundle;