humanish 0.104.3 → 0.106.0

package/dist/routes/terminal/sandbox.js

@@ -0,0 +1,126 @@
+import { toErrorMessage } from "../../evidence/redaction.js";
+import { E2BDesktopStartupError, isSandboxNotFoundError, } from "../../substrates/e2b/sdk.js";
+/**
+ * Tear the sandbox down and PROVE it BY EXACT ID -- NEVER Sandbox.list (humanish must never
+ * enumerate the operator's E2B account; see docs/principles/invariants-and-defaults.md). The
+ * allocation's release (src/substrates/e2b/sandbox.ts) kills the exact id and reads the answer the
+ * same way every route does: true is terminated, false or a not-found error is already gone. That
+ * is the PRIMARY proof. Where the SDK exposes Sandbox.getInfo(id), a thrown SandboxNotFoundError is
+ * a second by-id confirmation that the exact sandbox is gone; a returned SandboxInfo with a live
+ * state means teardown is NOT confirmed. Never throws -- teardown failure is recorded, the caller
+ * fails closed on an unproven teardown.
+ */
+export async function teardownSandbox(args) {
+    const { allocation, sandboxModule, startupCleanup, requestTimeoutMs, sanitize, recordLifecycle, warnings, } = args;
+    if (allocation === undefined || !sandboxModule) {
+        // create() can reject AFTER its constructor acquired a handle. The default loader retains
+        // that authority and reclaims it before rejecting; the lane itself never receives its ID.
+        if (startupCleanup === "killed" || startupCleanup === "already_gone") {
+            const reason = `desktop startup guard confirmed its acquired sandbox ${startupCleanup === "killed" ? "was killed" : "was already gone"}`;
+            recordLifecycle("terminal-lab.cleanup.killed", reason);
+            return { killed: true, remaining: 0, reason };
+        }
+        const reason = startupCleanup === "unconfirmed"
+            ? "desktop startup guard could not confirm cleanup of its acquired sandbox; provider timeout remains the backstop"
+            : "create did not return a sandbox; the participant has no acquired handle and cannot establish allocation or cleanup";
+        recordLifecycle("terminal-lab.cleanup.unconfirmed", reason);
+        return { killed: false, remaining: -1, reason };
+    }
+    const sandboxId = allocation.resourceId;
+    const released = await allocation.close();
+    if (released.status !== "released") {
+        if (released.status === "unconfirmed" && released.reason === "release_unavailable") {
+            return {
+                killed: false,
+                remaining: -1,
+                reason: "installed @e2b/desktop SDK does not expose Sandbox.kill; server-side kill-on-timeout will reclaim the sandbox",
+            };
+        }
+        if (released.status === "unconfirmed" && released.reason === "release_failed") {
+            const sanitizedError = sanitize(toErrorMessage(released.error));
+            warnings.push(`Sandbox teardown failed (server-side kill-on-timeout will reclaim it): ${sanitizedError}`);
+            recordLifecycle("terminal-lab.cleanup.kill_error", `Sandbox ${sandboxId} kill(id) failed: ${sanitizedError}`);
+            return {
+                killed: false,
+                remaining: -1,
+                reason: `kill(id) failed: ${sanitizedError} (server-side kill-on-timeout will reclaim it)`,
+            };
+        }
+        // kill(id) answered neither true nor false: nothing proves this id is gone.
+        const reason = "kill(id) returned neither true nor false; this sandbox's teardown is not confirmed by id (server-side kill-on-timeout remains the backstop)";
+        warnings.push(`Sandbox teardown unconfirmed: ${reason}`);
+        recordLifecycle("terminal-lab.cleanup.unconfirmed", `Sandbox ${sandboxId} ${reason}.`);
+        return { killed: false, remaining: -1, reason };
+    }
+    // BY-ID verification only, from here down: NEVER Sandbox.list. A released result is itself proof
+    // the exact sandbox is gone: terminated when kill(id) found and killed it, already gone when
+    // kill(id) answered false or threw not-found (a 404, e.g. the server-side kill-on-timeout raced
+    // ahead). Both mean "this id is no longer running." Sandbox.getInfo(id), when the SDK exposes
+    // it, adds a second by-id confirmation; the only thing that overturns the release proof is
+    // getInfo returning a LIVE sandbox for this exact id.
+    const killNote = released.reason === "terminated"
+        ? "kill(id) returned true (found and killed)"
+        : "kill(id) found the exact sandbox already gone (404)";
+    if (typeof sandboxModule.Sandbox.getInfo !== "function") {
+        recordLifecycle("terminal-lab.cleanup.killed", `Sandbox ${sandboxId} reclaimed: ${killNote}; the installed SDK has no getInfo(id) to re-verify, so kill(id)'s own result is the proof.`);
+        return {
+            killed: true,
+            remaining: 0,
+            reason: `reclaimed by id; ${killNote} and the installed SDK does not expose Sandbox.getInfo to re-verify`,
+        };
+    }
+    try {
+        const info = await sandboxModule.Sandbox.getInfo(sandboxId, { requestTimeoutMs });
+        const state = info.state ?? "unknown";
+        recordLifecycle("terminal-lab.cleanup.unconfirmed", `Sandbox ${sandboxId} ${killNote}, but getInfo(id) still reports state=${state} (not confirmed reclaimed by id).`);
+        return {
+            killed: true,
+            remaining: 1,
+            reason: `${killNote} but getInfo(id) still reports state=${state}; this sandbox's teardown is not confirmed by id`,
+        };
+    }
+    catch (error) {
+        if (isSandboxNotFoundError(error)) {
+            recordLifecycle("terminal-lab.cleanup.verified", `Sandbox ${sandboxId} reclaimed; getInfo(id) confirms it no longer exists (SandboxNotFoundError) -- by exact id, never re-listed.`);
+            return {
+                killed: true,
+                remaining: 0,
+                reason: `reclaimed by id; getInfo(id) confirms the exact sandbox no longer exists (SandboxNotFoundError)`,
+            };
+        }
+        // getInfo(id) failed for a reason OTHER than "not found" (e.g. a transient network error):
+        // no second by-id confirmation is available, so the RESOLVED kill(id) call stands as the proof
+        // of absence. Never fall back to Sandbox.list.
+        const sanitizedError = sanitize(toErrorMessage(error));
+        recordLifecycle("terminal-lab.cleanup.killed", `Sandbox ${sandboxId} reclaimed: ${killNote}; getInfo(id) re-verification errored (${sanitizedError}), so kill(id)'s resolved result is the proof.`);
+        return {
+            killed: true,
+            remaining: 0,
+            reason: `reclaimed by id; ${killNote} and getInfo(id) re-verification errored (${sanitizedError}), so kill(id)'s resolved result is the proof`,
+        };
+    }
+}
+/**
+ * Race a commands.run promise against the maxMinutes wall-clock (safety contract item 2). The E2B
+ * commands.run timeoutMs is the primary kill; this injected-clock guard is the belt-and-suspenders
+ * backstop so a mock CLI (which ignores timeoutMs) is still bounded and fails closed in CI.
+ */
+export async function runWithWallClock(promise, wallClockMs, now) {
+    let timer;
+    const start = now();
+    const timeout = new Promise((resolve) => {
+        timer = setTimeout(() => resolve({ timedOut: true }), wallClockMs);
+        timer.unref?.();
+    });
+    const value = await Promise.race([
+        promise.then((v) => ({ timedOut: false, value: v })),
+        timeout,
+    ]);
+    if (timer)
+        clearTimeout(timer);
+    // Guard against a clock that advanced past the budget even if the race resolved on the promise.
+    if (!value.timedOut && now() - start >= wallClockMs) {
+        return { timedOut: true };
+    }
+    return value;
+}

package/dist/routes/terminal/session.d.ts

@@ -0,0 +1,25 @@
+import type { LiveTerminalAuth, LiveTerminalPlan, RunLiveTerminalSessionArgs, TerminalProductLabErrorCode, TerminalProductLabResult, TerminalRunInput } from "./types.js";
+/**
+ * The checks of this machine a live run makes before its run starts: the runtime key and
+ * E2B_API_KEY. They read only the plan and the environment, so the CLI makes them before it loads
+ * a declared scorer. Returns the runtime key's command-scoped placement, or the refusal.
+ */
+export declare function checkLiveTerminalMachine(plan: LiveTerminalPlan, input: TerminalRunInput, warnings: string[]): {
+    readonly ok: true;
+    readonly runtimeEnv: LiveTerminalAuth;
+} | {
+    readonly ok: false;
+    readonly code: TerminalProductLabErrorCode;
+    readonly message: string;
+};
+/**
+ * The live in-sandbox agent session orchestrator (mirror of runCuaActorLab's E2B branch). Enforces
+ * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
+ * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * the redacted terminal event stream + normalized transcript, the agent report, and the
+ * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
+ */
+export declare function runLiveTerminalSession(args: RunLiveTerminalSessionArgs): Promise<TerminalProductLabResult>;
+/** The default mission when the lab omits one. Public-safe, product-neutral author text. */
+export declare function defaultMission(productName: string): string;
+export declare function makeTerminalRunId(): string;

package/dist/routes/terminal/session.js

@@ -0,0 +1,199 @@
+import { randomBytes, randomUUID } from "node:crypto";
+import { declaredRuntimeProvenance } from "./runtime.js";
+import { digestText, redactText, scrubLiterals } from "../../evidence/redaction.js";
+import { describeMissingKeys } from "../../keys/key-resolution.js";
+import { buildRunSource } from "../../run/bundle.js";
+import { renderTerminalReviewMarkdown } from "./bundle.js";
+import { buildRuntimeAuth, buildSandboxMetadata } from "./credentials.js";
+import { resolveTerminalPersona, terminalPersonaRef } from "./persona.js";
+import { createTerminalRecorder } from "./recorder.js";
+import { LiveTerminalSandbox } from "./live-sandbox.js";
+import { finishLiveTerminalSession } from "./live-finish.js";
+/**
+ * The checks of this machine a live run makes before its run starts: the runtime key and
+ * E2B_API_KEY. They read only the plan and the environment, so the CLI makes them before it loads
+ * a declared scorer. Returns the runtime key's command-scoped placement, or the refusal.
+ */
+export function checkLiveTerminalMachine(plan, input, warnings) {
+    const env = input.hooks?.env ?? process.env;
+    const { maxUsd } = plan.caps;
+    // planTerminalLab refuses a positive maxUsd without a costProbe, so one is present here.
+    if (maxUsd > 0) {
+        warnings.push(`scenario.caps.maxUsd=${maxUsd} is checked after the session against the lines the costProbe measures; lines it leaves null (unmeasured) never trip it. scenario.caps.maxMinutes bounds the run while it runs.`);
+    }
+    // --- Safety contract item 4: deny-by-default credentials; build the command-scoped allowlist. ---
+    const runtimeEnv = buildRuntimeAuth({ runtimeAuth: plan.runtime.auth, env });
+    if (!runtimeEnv.ok)
+        return runtimeEnv;
+    // The sandbox is created with E2B_API_KEY, so a missing key is refused before the run starts.
+    if (!env.E2B_API_KEY?.trim()) {
+        return {
+            ok: false,
+            code: "HUMANISH_TERMINAL_LAB_KEYS_MISSING",
+            message: `Live terminal-product labs need E2B_API_KEY in the environment (values are never persisted). ${describeMissingKeys(["E2B_API_KEY"], env)}`,
+        };
+    }
+    return { ok: true, runtimeEnv };
+}
+/**
+ * The live in-sandbox agent session orchestrator (mirror of runCuaActorLab's E2B branch). Enforces
+ * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
+ * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * the redacted terminal event stream + normalized transcript, the agent report, and the
+ * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
+ */
+export async function runLiveTerminalSession(args) {
+    const { plan, input, cwd, warnings, failed, scope, runtimeEnv } = args;
+    const { actor, product } = plan;
+    const { maxUsd, maxMinutes } = plan.caps;
+    const hooks = input.hooks ?? {};
+    const env = hooks.env ?? process.env;
+    const now = hooks.now ?? (() => Date.now());
+    const nowIso = () => new Date(now()).toISOString();
+    const prepared = await prepareLivePrompt({ plan, cwd, runtimeEnv, env, warnings });
+    const { mission, physicalCwd, persona, composedPrompt, verdictNonce } = prepared;
+    const { knownSecretValues, sanitize } = prepared;
+    const started = await scope.startRun({
+        cwd: physicalCwd,
+        runId: input.runId,
+        mintRunId: makeTerminalRunId,
+        // This entry point is the live terminal route; its dry-run sibling is a separate function.
+        mode: "live",
+        lab: plan.lab,
+        renderReview: renderTerminalReviewMarkdown,
+        observer: { open: input.open === true, render: hooks.renderObserverFn },
+        now,
+    });
+    if (!started.ok)
+        return failed(started.code, started.message);
+    const { run } = started;
+    const { runId, createdAt, paths: runPaths } = run;
+    const source = await buildRunSource({
+        capturedAt: createdAt,
+        cwd: physicalCwd,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
+    // The ledgers + capture buffers, mutated through the live lifecycle.
+    const recorder = createTerminalRecorder({ nowIso, sanitize, knownSecretValues });
+    const { version, model, reasoningEffort } = plan.runtime;
+    const runtime = declaredRuntimeProvenance({
+        ...(version === undefined ? {} : { version }),
+        ...(model === undefined ? {} : { model: sanitize(model) }),
+        ...(reasoningEffort === undefined ? {} : { reasoningEffort }),
+    });
+    recorder.recordLifecycle("terminal-lab.run.created", `Created live terminal-product run ${runId} (actor ${actor}, product ${product.name}). Caps: maxUsd=${maxUsd}, maxMinutes=${maxMinutes}. Subject provenance UNPINNED (public surfaces only).`);
+    const session = new LiveTerminalSandbox({
+        plan,
+        cwd,
+        hooks,
+        now,
+        nowIso,
+        sanitize,
+        runtimeEnv,
+        runtime,
+        composedPrompt,
+        verdictNonce,
+        maxMinutes,
+        e2bApiKey,
+        runPaths,
+        metadata: buildSandboxMetadata({ labId: plan.labId, simId: "sim-001", runId }),
+        warnings,
+        recorder,
+    });
+    try {
+        await session.acquire();
+        await session.probeReady();
+        // Each step fails the session closed and returns false; codex exec runs only after all pass.
+        if ((await session.bootstrap()) &&
+            (await session.verifyRuntimeVersion()) &&
+            (await session.prepareProduct())) {
+            await session.execCodex();
+        }
+    }
+    catch (error) {
+        session.recordSessionError(error);
+    }
+    finally {
+        await session.teardown();
+    }
+    return finishLiveTerminalSession({
+        plan,
+        input,
+        cwd,
+        hooks,
+        sanitize,
+        nowIso,
+        knownSecretValues,
+        runtimeEnv,
+        runtime,
+        persona,
+        mission,
+        run,
+        source,
+        warnings,
+        recorder,
+        session,
+    });
+}
+/**
+ * Composes the live prompt and the scrubbers: the mission, the committed persona, the verdict
+ * nonce, and the literal-scrub of every known secret value.
+ */
+async function prepareLivePrompt(args) {
+    const { plan, cwd, runtimeEnv, env, warnings } = args;
+    const { product } = plan;
+    // Compose the prompt from PUBLIC surfaces + the author mission ONLY (safety contract item 3).
+    // Inject a per-run verdict nonce: the agent echoes HUMANISH_ACTOR_VERDICT=<status>
+    // HUMANISH_ACTOR_NONCE=<nonce>; the scorer verifies the nonce so replayed text cannot forge it.
+    const mission = plan.mission ?? defaultMission(product.name);
+    const terminalPersona = await resolveTerminalPersona({ plan, cwd, warnings });
+    const verdictNonce = randomUUID().slice(0, 12);
+    const composedPrompt = composeLivePrompt({
+        mission,
+        personaLine: terminalPersona.personaLine,
+        productName: product.name,
+        publicSurfaces: product.publicSurfaces,
+        verdictNonce,
+    });
+    const promptDigest = digestText(composedPrompt);
+    // --- Safety contract item 5: literal-scrub EVERY known value, then pattern-redact, at the source. ---
+    // The runtime key value (+ any other provisioned value) is scrubbed by LITERAL match before
+    // anything persists (a key has no detectable "shape" if it is an arbitrary token); redactText is
+    // the second pass for secret-SHAPED content. Applied PRE-truncation so a cut can never split a
+    // value past the scrubber.
+    const knownSecretValues = [runtimeEnv.keyValue, env.E2B_API_KEY?.trim() ?? ""].filter((v) => v.length >= 4);
+    const scrubKnownValues = scrubLiterals(knownSecretValues);
+    const sanitize = (text) => redactText(scrubKnownValues(text));
+    const persona = terminalPersonaRef(terminalPersona, promptDigest, scrubKnownValues);
+    return {
+        mission,
+        physicalCwd: terminalPersona.physicalCwd,
+        persona,
+        composedPrompt,
+        verdictNonce,
+        knownSecretValues,
+        sanitize,
+    };
+}
+/** Compose the live prompt: PUBLIC surfaces + author mission + the verdict-nonce marker contract. */
+function composeLivePrompt(args) {
+    return [
+        args.personaLine,
+        `product: ${args.productName}`,
+        `public-surfaces: ${args.publicSurfaces.join(" ")}`,
+        `mission: ${args.mission}`,
+        "",
+        "Work ONLY from the public surfaces above. Do NOT clone or inspect any private repository.",
+        `When finished, print exactly one final machine-readable line in this format: HUMANISH_ACTOR_VERDICT=<status> HUMANISH_ACTOR_NONCE=${args.verdictNonce} where <status> is passed, blocked, or failed.`,
+    ].join("\n");
+}
+/** The default mission when the lab omits one. Public-safe, product-neutral author text. */
+export function defaultMission(productName) {
+    return `You are an autonomous agent. Discover ${productName} from its public surfaces and determine whether it can help with a durable real task. Stay within the declared no-spend caps. Leave feedback if the workflow is confusing.`;
+}
+export function makeTerminalRunId() {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `terminal-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/routes/terminal/token-usage.d.ts

@@ -0,0 +1,15 @@
+import type { ActorTokenUsage } from "../../actors/contract.js";
+/**
+ * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
+ * include multiple provider requests; these records cannot establish per-request pricing tiers.
+ *
+ * Returns undefined when the stream carried no usage record at all, which is the honest "no
+ * signal" case and must stay distinguishable from a measured zero. Per-turn records are preserved
+ * in `turns` because long-context pricing can only be computed from per-request sizes
+ * (src/run/pricing.ts), and totals cannot say which requests crossed a threshold.
+ */
+export declare function parseTerminalTokenUsage(transcript: string): ActorTokenUsage | undefined;
+/** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
+ *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
+ *  "nothing was consumed". */
+export declare function describeTokenUsage(usage: ActorTokenUsage): string;

package/dist/routes/terminal/token-usage.js

@@ -0,0 +1,93 @@
+// Provider token accounting for the terminal lane (#531).
+//
+// THE GAP THIS CLOSES. A live terminal run reported `cost.lines.provider = null` with source
+// "unmeasured", and the no-spend proof then read `satisfied: true` for `maxUsd: 0` on a run that
+// had demonstrably consumed hundreds of thousands of provider tokens. The statement was honest
+// (it listed provider as unmeasured) but it conflated two very different states: having no signal
+// at all, and knowing exactly how many tokens were spent while lacking a rate to price them.
+//
+// The counts were already in the bundle. `codex exec --json` emits one usage record per turn:
+//   {"type":"turn.completed","usage":{"input_tokens":201536,"cached_input_tokens":170558,
+//    "cache_write_input_tokens":30951,"output_tokens":2283,"reasoning_output_tokens":902}}
+//
+// So the lane can record a MEASURED token fact even when it cannot record a priced one. Rates stay
+// out of this module deliberately: pricing lives in src/run/pricing.ts, and the terminal lane has no
+// real model id to price against (it records `model: "codex"`), so the honest output is
+// tokens-known-rate-unknown rather than a guessed dollar figure.
+// Bounded to a single line on purpose. `[^}]*` would run past a TRUNCATED record's missing brace
+// and swallow the next, valid record's body, silently dropping a real turn from the count.
+const USAGE_RE = /"type"\s*:\s*"turn\.completed"\s*,\s*"usage"\s*:\s*(\{[^}\n]*\})/g;
+function num(value) {
+    return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
+}
+/**
+ * Accumulate runtime-turn usage from a captured `codex exec --json` stream. A Codex turn may
+ * include multiple provider requests; these records cannot establish per-request pricing tiers.
+ *
+ * Returns undefined when the stream carried no usage record at all, which is the honest "no
+ * signal" case and must stay distinguishable from a measured zero. Per-turn records are preserved
+ * in `turns` because long-context pricing can only be computed from per-request sizes
+ * (src/run/pricing.ts), and totals cannot say which requests crossed a threshold.
+ */
+export function parseTerminalTokenUsage(transcript) {
+    const turns = [];
+    for (const match of transcript.matchAll(USAGE_RE)) {
+        const body = match[1];
+        if (body === undefined)
+            continue;
+        let raw;
+        try {
+            raw = JSON.parse(body);
+        }
+        catch {
+            continue; // A truncated or interleaved record is skipped rather than guessed at.
+        }
+        const input = num(raw.input_tokens);
+        const output = num(raw.output_tokens);
+        const cachedInput = num(raw.cached_input_tokens);
+        const cacheWriteInput = num(raw.cache_write_input_tokens);
+        if (input === undefined && output === undefined)
+            continue;
+        turns.push({
+            ...(input === undefined ? {} : { input }),
+            ...(output === undefined ? {} : { output }),
+            ...(cachedInput === undefined ? {} : { cachedInput }),
+            ...(cacheWriteInput === undefined ? {} : { cacheWriteInput }),
+        });
+    }
+    if (turns.length === 0)
+        return undefined;
+    const sum = (field) => {
+        const present = turns.filter((t) => t[field] !== undefined);
+        if (present.length === 0)
+            return undefined;
+        return present.reduce((acc, t) => acc + (t[field] ?? 0), 0);
+    };
+    const input = sum("input");
+    const output = sum("output");
+    const cachedInput = sum("cachedInput");
+    const cacheWriteInput = sum("cacheWriteInput");
+    return {
+        ...(input === undefined ? {} : { input }),
+        ...(output === undefined ? {} : { output }),
+        ...(cachedInput === undefined ? {} : { cachedInput }),
+        ...(cacheWriteInput === undefined ? {} : { cacheWriteInput }),
+        ...(input === undefined && output === undefined ? {} : { total: (input ?? 0) + (output ?? 0) }),
+        turns,
+    };
+}
+/** Human-readable token statement for the cost ledger and the no-spend proof. Reports what was
+ *  counted and says plainly that it is unpriced, so a reader never reads "no charge recorded" as
+ *  "nothing was consumed". */
+export function describeTokenUsage(usage) {
+    const parts = [];
+    if (usage.input !== undefined)
+        parts.push(`${usage.input.toLocaleString("en-US")} input`);
+    if (usage.cachedInput !== undefined) {
+        parts.push(`${usage.cachedInput.toLocaleString("en-US")} of them cached`);
+    }
+    if (usage.output !== undefined)
+        parts.push(`${usage.output.toLocaleString("en-US")} output`);
+    const turns = usage.turns?.length ?? 0;
+    return `${parts.join(", ")} tokens over ${turns} Codex turn${turns === 1 ? "" : "s"}`;
+}

package/dist/routes/terminal/trace.d.ts

@@ -0,0 +1,40 @@
+import type { ActorCompletionReason, ActorPersonaRef, ActorRuntimeProvenance, ActorStatus, ActorTokenUsage, ActorTrace } from "../../actors/contract.js";
+import type { LabRuntimeAuth } from "../../lab/types.js";
+import { type CommandLogRecord, type TerminalEventRecord } from "./types.js";
+/**
+ * Per-chunk sanitization cannot recognize a value split across deliveries. Redact those complete
+ * known values before persistence without collapsing events or changing stdout/stderr ordering.
+ * Work backwards through matches so edits to later text leave earlier offsets valid.
+ */
+export declare function scrubSplitKnownValues(events: TerminalEventRecord[], knownValues: string[], discardedPrefixes: Record<"stdout" | "stderr" | "combined", string>): void;
+/** Redacted, ellipsis-prefixed tail of a captured stream/log for a message field. */
+export declare function tailOf(text: string): string;
+/**
+ * Project the live terminal session into the provider-neutral humanish.actor-trace.v1 (lane
+ * "terminal", protocol "terminal-exec"). counts.actions/messages drive the no-engagement honesty
+ * guard (a real run bumps them; a no-op is caught). No screenshots on this lane.
+ */
+export declare function buildTerminalActorTrace(args: {
+    persona: ActorPersonaRef;
+    productName: string;
+    status: ActorStatus;
+    completionReason: ActorCompletionReason;
+    reason: string;
+    createdAt: string;
+    completedAt: string;
+    durationMs: number;
+    terminalEvents: TerminalEventRecord[];
+    commandLog: CommandLogRecord[];
+    transcriptTail: string;
+    runtimeAuth: LabRuntimeAuth;
+    runtime: ActorRuntimeProvenance;
+    /** Runtime-turn aggregate usage parsed from the exec stream (#531). Absent when the stream
+     *  carried no usage record, which stays distinct from a measured zero. */
+    tokenUsage?: ActorTokenUsage;
+}): ActorTrace;
+/** Count distinct participant items in the retained Codex JSON stdout stream.
+ * The caller supplies stdout only, after transport reconciliation and redaction.
+ * Lifecycle, usage, launcher diagnostics, and nested command output are not activity.
+ * Zero means no recognized item was retained, not that the participant succeeded.
+ */
+export declare function countTerminalParticipantItems(stdout: string): number;