humanish 0.111.1 → 0.111.3

package/dist/routes/shared-world/setup.js

@@ -1,8 +1,7 @@
 // Starts a concurrent shared-world run and prepares what its plane reads: the physical project,
 // the run, the participant specs, comms, the packed tree and email receiving.
-import { randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
-import { buildRunSource } from "../../run/bundle.js";
+import {} from "../../run/bundle.js";
 import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
 import { renderConcurrentReviewMarkdown } from "./bundle.js";
 import { seedRecipeDigest } from "./checkpoints.js";
@@ -15,10 +14,6 @@ import { planeStateOf } from "./plan.js";
 import path from "node:path";
 import { e2bRequestTimeoutMs } from "../../substrates/e2b/lifetime.js";
 const DEFAULT_PROBER_CADENCE_MS = 1000;
-function makeRunId() {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return `concurrent-shared-world-${stamp}-${randomBytes(4).toString("hex")}`;
-}
 /** The provisioned plane's setup, or undefined when the study declares no `subject.serve`. */
 function provisionedSetup(study, prepared) {
     if (!study.serve)
@@ -49,16 +44,11 @@ async function bindPhysicalProject(requestedCwd) {
         .physicalPath;
 }
 function startConcurrentRun(study, cwd, scope) {
-    const { plan, input, deps } = study;
-    return scope.startRun({
+    return scope.startRun(study.plan, study.input, {
         cwd,
-        runId: input.runId,
-        mintRunId: makeRunId,
-        mode: plan.dryRun ? "dry-run" : "live",
-        study: plan.study,
-        warnings: plan.warnings,
+        prefix: "concurrent-shared-world",
         renderReview: renderConcurrentReviewMarkdown,
-        observer: { open: input.open === true, render: deps.renderObserver },
+        secrets: study.secrets,
     });
 }
 /**
@@ -67,8 +57,8 @@ function startConcurrentRun(study, cwd, scope) {
  */
 export async function prepareConcurrentRun(study, scope) {
     const { plan, input, config, requestedCwd, deps, env, descriptor, planeClass, fail } = study;
-    const { runBudget, runSession, localTreeRoute, subjectEnvNames, publicRepo } = study;
-    const { openaiApiKey, e2bApiKey, knownSecretValues, scrubKnownValues } = study;
+    const { runSession, localTreeRoute, subjectEnvNames, publicRepo } = study;
+    const { openaiApiKey, e2bApiKey, secrets } = study;
     const { dryRun, concurrency } = plan;
     const cwd = await bindPhysicalProject(requestedCwd);
     const warnings = [];
@@ -81,7 +71,7 @@ export async function prepareConcurrentRun(study, scope) {
     // Pack the working tree once per run, on the host, before any sandbox exists: a packing
     // failure fails the run closed without sandbox cost. Dry-run packs nothing.
     const packed = localTreeRoute && !dryRun
-        ? await packSubjectTree(cwd, plan.residual, deps, scrubKnownValues)
+        ? await packSubjectTree(cwd, plan.residual, deps, secrets.scrub)
         : { ok: true, archive: undefined, buffer: undefined };
     if (!packed.ok) {
         return {
@@ -95,7 +85,7 @@ export async function prepareConcurrentRun(study, scope) {
     if (!started.ok)
         return { ok: false, result: fail(started.code, started.message, descriptor.id) };
     const { run } = started;
-    const { runId, createdAt, paths: runPaths } = run;
+    const { runId, createdAt, paths: runPaths, source } = run;
     const artifactRoot = runPaths.absoluteRunRoot;
     const timeoutMs = plan.sessionTimeoutMs ?? defaultSessionTimeoutMs(plan);
     const requestTimeoutMs = e2bRequestTimeoutMs(env);
@@ -104,15 +94,9 @@ export async function prepareConcurrentRun(study, scope) {
     const now = deps.now ?? Date.now;
     const proberCadenceMs = deps.proberCadenceMs ?? DEFAULT_PROBER_CADENCE_MS;
     const seedDigest = seedRecipeDigest(planeStateOf(plan));
-    const source = await buildRunSource({
-        capturedAt: createdAt,
-        cwd,
-        humanishSource: "present",
-        packageName: "humanish",
-    });
     const stateStepRecords = [];
     const stateSnapshots = [];
-    const actorSpecs = await buildParticipantSpecs(plan.plane.participants, cwd, scrubKnownValues);
+    const actorSpecs = await buildParticipantSpecs(plan.plane.participants, cwd, run.secrets.scrub);
     const results = emptyPlaneResults();
     const live = { streamUrls: [] };
     const subjectComms = subjectCommsOf(plan.residual, planeClass);
@@ -124,7 +108,7 @@ export async function prepareConcurrentRun(study, scope) {
         env,
         participants: actorSpecs.map((spec) => spec.planned.id),
         runPaths,
-        knownSecretValues,
+        secrets: run.secrets,
         dryRun,
     });
     if (!email.ok) {
@@ -148,12 +132,10 @@ export async function prepareConcurrentRun(study, scope) {
         deps,
         env,
         concurrency,
-        runBudget,
         runSession,
         openaiApiKey,
         e2bApiKey,
-        scrubKnownValues,
-        knownSecretValues,
+        scrubKnownValues: run.secrets.scrub,
         cwd,
         run,
         runId,

package/dist/routes/shared-world/types.d.ts

@@ -7,7 +7,7 @@ import type { AutomaticAnalysisResult } from "../../analysis/automatic-completio
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
 import type { StudyCommsEmail, StudyCommsExternal, StudyConfig } from "../../study/types.js";
-import type { DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
+import type { SubjectDesktopUsage } from "../../substrates/e2b/subject-sandbox.js";
 import type { ObserverResult } from "../../observer/render.js";
 import type { ObserverRuntimeStreamUrl } from "../../observer/run-routes.js";
 import type { BundleRun, RunBundle, RunScorerProvenance, RunSubjectProvenance, RunSubjectStateStepRecord } from "../../run/bundle.js";
@@ -15,10 +15,10 @@ import type { RunScope } from "../../run/run.js";
 import type { SharedWorldStateSnapshot } from "../../run/shared-world-evidence.js";
 import type { LocalTreeArchive } from "../../subject/local-tree-archive.js";
 import type { LiveTraceFlush } from "../computer-use/live-flush.js";
-import type { CuaParticipantDeps, DesktopParticipantRun, CuaRunBudget, ParticipantRunOutcome } from "../computer-use/types.js";
+import type { CuaParticipantDeps, DesktopParticipantRun, ParticipantRunOutcome } from "../computer-use/types.js";
 import type { ProvisionedPlaneSetup } from "./provisioned.js";
 import type { SharedWorldPlan } from "../../study/plan-types.js";
-import { type StudyResultIdentity } from "../../run/study-result.js";
+import { type StudyResultErrorCode, type StudyResultIdentity } from "../../run/study-result.js";
 export declare const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA: {
     readonly mode: "concurrent-shared-world-lab";
     readonly tool: "humanish";
@@ -54,13 +54,13 @@ export interface SharedWorldRunInput {
      *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
-export type ConcurrentSharedWorldStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_SHARED_WORLD_FAILED" | "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_INVALID" | "HUMANISH_SHARED_WORLD_KEYS_MISSING"
+export type ConcurrentSharedWorldStudyErrorCode = StudyResultErrorCode | "HUMANISH_SHARED_WORLD_FAILED" | "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED" | "HUMANISH_SHARED_WORLD_INVALID" | "HUMANISH_SHARED_WORLD_KEYS_MISSING"
 /** A local-agent brain's CLI is not on `PATH`. */
  | "HUMANISH_SHARED_WORLD_AGENT_MISSING"
 /** A local-agent brain's CLI is signed out, or could not report its sign-in status. */
  | "HUMANISH_SHARED_WORLD_AGENT_SIGNIN_REQUIRED"
 /** A dollar cap that cannot be priced: an unpriced model, or a ChatGPT-account Codex brain. */
- | "HUMANISH_SHARED_WORLD_UNPRICED_CAP" | "HUMANISH_SHARED_WORLD_SUBJECT_ENV_MISSING" | "HUMANISH_SHARED_WORLD_GETHOST_UNAVAILABLE" | "HUMANISH_SHARED_WORLD_HANDOFF_TIMEOUT" | "HUMANISH_RUN_ID_IN_USE"
+ | "HUMANISH_SHARED_WORLD_UNPRICED_CAP" | "HUMANISH_SHARED_WORLD_SUBJECT_ENV_MISSING" | "HUMANISH_SHARED_WORLD_GETHOST_UNAVAILABLE" | "HUMANISH_SHARED_WORLD_HANDOFF_TIMEOUT"
 /** A declared adopter-hosted comms catch did not answer as a humanish catch. Fail closed
  *  before any actor spend, since the funnel would silently collect nothing. */
  | "HUMANISH_SHARED_WORLD_COMMS_CATCH_UNREACHABLE"
@@ -134,12 +134,6 @@ export interface ConcurrentSharedWorldStudyResult extends AutomaticAnalysisResul
         message: string;
     };
 }
-/** The provisioned plane's own desktop, for the run's cost estimate. */
-export interface SubjectDesktopUsage {
-    durationMs: number | undefined;
-    observation: DesktopResourceObservation | undefined;
-    killed: boolean;
-}
 /** One actor's measured run (internal). */
 export interface ActorRunResult {
     spec: DesktopParticipantRun;
@@ -163,14 +157,11 @@ export interface PlaneContext {
     deps: StudyDeps;
     env: Record<string, string | undefined>;
     concurrency: number;
-    runBudget: CuaRunBudget | undefined;
     runSession: CuaParticipantDeps["runSession"];
     openaiApiKey: string;
     e2bApiKey: string;
+    /** `run.secrets.scrub`, which every plane step that writes text reads. */
     scrubKnownValues: (text: string) => string;
-    /** The values scrubKnownValues removes. Real email receiving adds its secrets before participants
-     *  start. */
-    knownSecretValues: readonly string[];
     cwd: string;
     run: StartedRun;
     runId: string;

package/dist/routes/terminal/dry-run.js

@@ -1,14 +1,15 @@
 // The terminal route's dry run: a contract-only bundle with the persona and prompt digest bound,
 // published through the run scope with no sandbox, key or spend. session.ts holds the live path.
-import { digestText, redactText, scrubLiterals } from "../../evidence/redaction.js";
+import { digestText, redactText } from "../../evidence/redaction.js";
 import { participantAssignment } from "../../study/participant-assignment.js";
-import { buildRunSource } from "../../run/bundle.js";
+import {} from "../../run/bundle.js";
 import { judgeExecution, judgeTerminal, OUTCOME_POLICIES, resultOk } from "../../run/judge.js";
 import { validatePreparedRunArtifactPaths } from "../../run/paths.js";
+import { RunSecrets } from "../../run/secrets.js";
 import { buildTerminalProductBundle, renderTerminalReviewMarkdown } from "./bundle.js";
 import { resolveTerminalPersona, terminalPersonaRef } from "./persona.js";
 import { declaredRuntimeProvenance } from "./runtime.js";
-import { defaultMission, makeTerminalRunId } from "./session.js";
+import { defaultMission } from "./session.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
 /**
@@ -18,32 +19,22 @@ import { studyResultIdentity } from "../../run/study-result.js";
 export async function runDryTerminalStudy(args) {
     const { plan, input, cwd, warnings, failed, scope } = args;
     const { product } = plan;
-    const { evidenceMission, physicalCwd, persona } = await prepareDryPersona({
+    const { evidenceMission, physicalCwd, persona, secrets } = await prepareDryPersona({
         plan,
         cwd,
         env: input.env ?? process.env,
         warnings,
     });
-    const started = await scope.startRun({
+    const started = await scope.startRun(plan, input, {
         cwd: physicalCwd,
-        runId: input.runId,
-        mintRunId: makeTerminalRunId,
-        mode: "dry-run",
-        study: plan.study,
-        warnings: plan.warnings,
+        prefix: "terminal",
         renderReview: renderTerminalReviewMarkdown,
-        observer: { open: input.open === true, render: input.deps?.renderObserver },
+        secrets,
     });
     if (!started.ok)
         return failed(started.code, started.message);
     const { run } = started;
-    const { runId, createdAt } = run;
-    const source = await buildRunSource({
-        capturedAt: createdAt,
-        cwd: physicalCwd,
-        humanishSource: "present",
-        packageName: "humanish",
-    });
+    const { runId, createdAt, source } = run;
     const policies = plan.residual.policies;
     const judgment = judgeTerminal({ dryRun: true, participant: undefined });
     const bundle = buildTerminalProductBundle({
@@ -107,10 +98,9 @@ async function prepareDryPersona(args) {
     const { plan, cwd, env, warnings } = args;
     const { product } = plan;
     const mission = plan.mission ?? defaultMission(product.name);
-    const knownSecretValues = [env.CODEX_API_KEY, env.OPENAI_API_KEY, env.E2B_API_KEY]
-        .map((value) => value?.trim() ?? "")
-        .filter((value) => value.length >= 4);
-    const evidenceMission = participantAssignment({ mission }, scrubLiterals(knownSecretValues)).mission;
+    // A dry run checks no key, so it scrubs every key the live run could read.
+    const secrets = new RunSecrets([env.CODEX_API_KEY, env.OPENAI_API_KEY, env.E2B_API_KEY].map((value) => value?.trim() ?? ""));
+    const evidenceMission = participantAssignment({ mission }, secrets.scrub).mission;
     const terminalPersona = await resolveTerminalPersona({ plan, cwd, warnings });
     // The composed prompt = mission + persona + public-surface manifest. Only the author mission
     // goes plaintext into evidence (it is public-safe committed study text); the full composed prompt
@@ -121,9 +111,9 @@ async function prepareDryPersona(args) {
         productName: product.name,
         publicSurfaces: product.publicSurfaces,
     });
-    const persona = terminalPersonaRef(terminalPersona, digestText(composedPrompt), scrubLiterals(knownSecretValues));
+    const persona = terminalPersonaRef(terminalPersona, digestText(composedPrompt), secrets.scrub);
     const { physicalCwd } = terminalPersona;
-    return { evidenceMission, physicalCwd, persona };
+    return { evidenceMission, physicalCwd, persona, secrets };
 }
 /** The declared runtime provenance as a dry-run event; nothing is observed without a sandbox. */
 function runtimeDeclaredEvent(runtime, createdAt) {

package/dist/routes/terminal/live-finish.d.ts

@@ -13,7 +13,6 @@ export interface LiveFinishInputs {
     cwd: string;
     sanitize: (text: string) => string;
     nowIso: () => string;
-    knownSecretValues: string[];
     runtimeEnv: LiveSandboxInputs["runtimeEnv"];
     runtime: LiveSandboxInputs["runtime"];
     persona: ActorPersonaRef;

package/dist/routes/terminal/live-finish.js

@@ -14,7 +14,7 @@ import { terminalExecutionFailures, terminalStudyResult, terminalParticipantFact
 import { parseTerminalTokenUsage } from "./token-usage.js";
 import { buildTerminalActorTrace, scrubSplitKnownValues, tailOf } from "./trace.js";
 function buildLiveTrace(inputs) {
-    const { persona, sanitize, nowIso, runtimeEnv, runtime, knownSecretValues } = inputs;
+    const { persona, sanitize, nowIso, runtimeEnv, runtime } = inputs;
     const { product } = inputs.plan;
     const { session } = inputs;
     const { createdAt } = inputs.run;
@@ -22,7 +22,7 @@ function buildLiveTrace(inputs) {
     // Prefix reconciliation may cut through a known key. Scrub literal values across the retained
     // chunks before any transcript/trace/event artifact is persisted. Check both each stream and
     // the combined event order that the transcript uses; either view can assemble a split value.
-    scrubSplitKnownValues(terminalEvents, knownSecretValues, discardedPrefixes);
+    scrubSplitKnownValues(terminalEvents, inputs.run.secrets.values(), discardedPrefixes);
     // Build the actor trace first (the cost ledger reads its tokenUsage). A session past the cap
     // ends its transcript with what was not stored, and its trace says the same.
     const cut = inputs.recorder.transcriptCut();

package/dist/routes/terminal/route.js

@@ -53,21 +53,20 @@ import { checkLiveTerminalMachine, runLiveTerminalSession } from "./session.js";
 import { terminalRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
-import { studyResultIdentity } from "../../run/study-result.js";
+import { refusedResult } from "../../run/study-result.js";
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
 export function terminalStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
-    const refused = {
-        ...studyResultIdentity("terminal", config.id),
-        ok: false,
+    const refused = refusedResult("terminal", {
+        studyId: config.id,
         cwd: path.resolve(options.cwd),
+        error: { code: refusal.code, message: refusal.message },
+    }, {
         actor: refusal.actor ?? config.actor?.type ?? "",
         product: config.subject.product?.name ?? "",
         dryRun,
         runId: options.runId ?? "not-created",
-        warnings: [],
-        error: { code: refusal.code, message: refusal.message },
-    };
+    });
     return completeRefusalAnalysis(refused, config, options);
 }
 /**
@@ -86,11 +85,11 @@ export function admitTerminalPlan(plan, input) {
     });
 }
 /** A live plan's local checks, made outside any run scope. */
-function admitTerminalRun(plan, input) {
+async function admitTerminalRun(plan, input) {
     const warnings = [];
     if (plan.dryRun)
         return { ok: true, admitted: { plan, warnings } };
-    const checked = checkLiveTerminalMachine(plan, input, warnings);
+    const checked = await checkLiveTerminalMachine(plan, input, warnings);
     if (checked.ok)
         return { ok: true, admitted: { plan, warnings, runtimeEnv: checked.runtimeEnv } };
     return {
@@ -101,16 +100,11 @@ function admitTerminalRun(plan, input) {
 /** The route's envelope for a run that stops before its bundle. */
 function terminalFailure(plan, input, warnings) {
     const cwd = path.resolve(input.cwd);
-    return (code, message) => ({
-        ...studyResultIdentity("terminal", plan.studyId),
-        ok: false,
-        cwd,
+    return (code, message) => refusedResult("terminal", { studyId: plan.studyId, cwd, warnings, error: { code, message } }, {
         actor: plan.actor,
         product: plan.product.name,
         dryRun: plan.dryRun,
         runId: input.runId ?? "not-created",
-        warnings,
-        error: { code, message },
     });
 }
 async function runTerminalPlanInScope(admitted, input, scope) {

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

@@ -4,14 +4,14 @@ import type { LiveTerminalAuth, LiveTerminalPlan, RunLiveTerminalSessionArgs, Te
  * 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[]): {
+export declare function checkLiveTerminalMachine(plan: LiveTerminalPlan, input: TerminalRunInput, warnings: string[]): Promise<{
     readonly ok: true;
     readonly runtimeEnv: LiveTerminalAuth;
 } | {
     readonly ok: false;
     readonly code: TerminalProductStudyErrorCode;
     readonly message: string;
-};
+}>;
 /**
  * The live in-sandbox agent session orchestrator. 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,
@@ -21,4 +21,3 @@ export declare function checkLiveTerminalMachine(plan: LiveTerminalPlan, input:
 export declare function runLiveTerminalSession(args: RunLiveTerminalSessionArgs): Promise<TerminalProductStudyResult>;
 /** The default mission when the study 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

@@ -1,9 +1,8 @@
-import { randomBytes, randomUUID } from "node:crypto";
-import { missingKeys } from "../../study/requirements.js";
+import { randomUUID } from "node:crypto";
+import { keysCheck } from "../../study/requirements.js";
 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 { digestText, redactText } from "../../evidence/redaction.js";
+import { RunSecrets } from "../../run/secrets.js";
 import { renderTerminalReviewMarkdown } from "./bundle.js";
 import { buildRuntimeAuth, buildSandboxMetadata } from "./credentials.js";
 import { resolveTerminalPersona, terminalPersonaRef } from "./persona.js";
@@ -15,7 +14,7 @@ import { finishLiveTerminalSession } from "./live-finish.js";
  * 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) {
+export async function checkLiveTerminalMachine(plan, input, warnings) {
     const env = input.env ?? process.env;
     const { maxUsd } = plan.caps;
     // planTerminalStudy refuses a positive maxUsd without a costProbe, so one is present here.
@@ -28,13 +27,14 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
         return runtimeEnv;
     // The sandbox is created with E2B_API_KEY, so a missing key is refused before the run starts.
     // The runtime key above is the plan's `key-one-of`; E2B_API_KEY is its only `key`.
-    if (missingKeys(plan.requirements, env).length > 0) {
-        return {
-            ok: false,
-            code: "HUMANISH_TERMINAL_KEYS_MISSING",
-            message: `Live terminal-product studies need E2B_API_KEY in the environment (values are never persisted). ${describeMissingKeys(["E2B_API_KEY"], env)}`,
-        };
-    }
+    const keys = await keysCheck({
+        requirements: plan.requirements,
+        env,
+        code: "HUMANISH_TERMINAL_KEYS_MISSING",
+        need: (names) => `Live terminal-product studies need ${names} in the environment (values are never persisted).`,
+    });
+    if (keys)
+        return { ok: false, ...keys };
     return { ok: true, runtimeEnv };
 }
 /**
@@ -53,32 +53,26 @@ export async function runLiveTerminalSession(args) {
     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({
+    const { secrets, sanitize } = prepared;
+    const started = await scope.startRun(plan, input, {
         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",
-        study: plan.study,
-        warnings: plan.warnings,
+        prefix: "terminal",
         renderReview: renderTerminalReviewMarkdown,
-        observer: { open: input.open === true, render: deps.renderObserver },
         now,
+        secrets,
     });
     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 { runId, paths: runPaths, source } = run;
     const e2bApiKey = env.E2B_API_KEY?.trim() ?? "";
     // The ledgers + capture buffers, mutated through the live lifecycle.
-    const recorder = createTerminalRecorder({ nowIso, sanitize, knownSecretValues, verdictNonce });
+    const recorder = createTerminalRecorder({
+        nowIso,
+        sanitize,
+        knownSecretValues: run.secrets.values(),
+        verdictNonce,
+    });
     const { version, model, modelSource, reasoningEffort } = plan.runtime;
     const runtime = declaredRuntimeProvenance({
         ...(version === undefined ? {} : { version }),
@@ -128,7 +122,6 @@ export async function runLiveTerminalSession(args) {
         cwd,
         sanitize,
         nowIso,
-        knownSecretValues,
         runtimeEnv,
         runtime,
         persona,
@@ -166,17 +159,16 @@ async function prepareLivePrompt(args) {
     // 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);
+    const secrets = new RunSecrets([runtimeEnv.keyValue, env.E2B_API_KEY?.trim() ?? ""]);
+    const sanitize = (text) => redactText(secrets.scrub(text));
+    const persona = terminalPersonaRef(terminalPersona, promptDigest, secrets.scrub);
     return {
         mission,
         physicalCwd: terminalPersona.physicalCwd,
         persona,
         composedPrompt,
         verdictNonce,
-        knownSecretValues,
+        secrets,
         sanitize,
     };
 }
@@ -197,7 +189,3 @@ function composeLivePrompt(args) {
 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/trace.d.ts

@@ -7,7 +7,7 @@ import { type CommandLogRecord, type TerminalEventRecord } from "./types.js";
  * 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;
+export declare function scrubSplitKnownValues(events: TerminalEventRecord[], knownValues: readonly 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;
 /**

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

@@ -8,7 +8,7 @@ import type { TerminalPlan } from "../../study/plan-types.js";
 import type { StudyDeps } from "../../study/study-deps.js";
 import type { ObserverResult } from "../../observer/render.js";
 import { type RunAdapterScore, type RunBundle, type RunFeedbackCandidate, type RunScorerProvenance } from "../../run/bundle.js";
-import { type StudyResultIdentity } from "../../run/study-result.js";
+import { type StudyResultErrorCode, type StudyResultIdentity } from "../../run/study-result.js";
 /** Provider-neutral metadata constant: the route's non-secret tag (mirrors CUA_ACTOR_STUDY_PROVIDER_METADATA). */
 export declare const TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA: {
     readonly mode: "terminal-product-lab";
@@ -172,7 +172,7 @@ export interface TerminalProductStudyResult extends AutomaticAnalysisResult, Stu
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN" | "HUMANISH_RUN_ID_IN_USE";
+        code: StudyResultErrorCode | "HUMANISH_TERMINAL_FAILED" | "HUMANISH_TERMINAL_ACTOR_UNSUPPORTED" | "HUMANISH_TERMINAL_SUBJECT_INVALID" | "HUMANISH_TERMINAL_KEYPLACEMENT_INVALID" | "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING" | "HUMANISH_TERMINAL_KEYS_MISSING" | "HUMANISH_TERMINAL_CAPS_MISSING" | "HUMANISH_TERMINAL_CAPS_INVALID" | "HUMANISH_TERMINAL_UNPRICED_CAP" | "HUMANISH_TERMINAL_CAPS_EXCEEDED" | "HUMANISH_TERMINAL_CREDENTIAL_DENIED" | "HUMANISH_TERMINAL_CLEANUP_UNPROVEN";
         message: string;
     };
 }

package/dist/run/run.d.ts

@@ -2,6 +2,7 @@ import { renderObserver, type ObserverResult } from "../observer/render.js";
 import { type RunBundle } from "./bundle.js";
 import { type ExecutionFailure, type ExecutionOutcome, type OutcomePolicy } from "./judge.js";
 import { type PreparedRunArtifactPaths, type RunIdInUse } from "./paths.js";
+import { RunSecrets } from "./secrets.js";
 import type { RunStudyProvenance } from "./study-provenance.js";
 interface StartRunOptions {
     /** Project directory, in the form the route resolved it. */
@@ -24,6 +25,41 @@ interface StartRunOptions {
     now?: (() => number) | undefined;
     /** Warnings about the study's own fields. Every bundle write records each as a warn event. */
     warnings?: readonly string[] | undefined;
+    /** The route's known values, created before the run so a refusal before it is scrubbed too. */
+    secrets?: RunSecrets | undefined;
+}
+/** The prefix of the run ids each recorded route mints. Preview mints its own `dryrun-` ids. */
+type RunIdPrefix = "cua" | "concurrent-shared-world" | "scripted" | "terminal";
+/** What a recorded route's plan holds for its run's start. */
+interface StartRunPlan {
+    readonly dryRun: boolean;
+    readonly study?: RunStudyProvenance | undefined;
+    readonly warnings?: readonly string[] | undefined;
+}
+/** What a recorded route's input holds for its run's start. */
+interface StartRunInput {
+    /** Caller-supplied id (`--run-id`, library `runId`); one is minted from the prefix when absent. */
+    readonly runId?: string | undefined;
+    /** Open the Observer page once it renders. */
+    readonly open?: boolean | undefined;
+    /** `renderObserver` is the seam FinishedRun.renderObserver calls. */
+    readonly deps?: {
+        readonly renderObserver?: typeof renderObserver | undefined;
+    } | undefined;
+}
+/** What a recorded route passes to startRun besides its plan and input. */
+interface RouteRunOptions {
+    /** Project directory, in the form the route resolved it. */
+    cwd: string;
+    prefix: RunIdPrefix;
+    /** review.md for the published bundle. */
+    renderReview: (bundle: RunBundle) => string;
+    /** `none` when the route creates no sandbox for this run; status.json records it for reclaim. */
+    sandboxes?: "none" | undefined;
+    /** Clock for `createdAt` and the latest pointer. The minted id reads the wall clock. */
+    now?: (() => number) | undefined;
+    /** The route's known values, created before the run so a refusal before it is scrubbed too. */
+    secrets?: RunSecrets | undefined;
 }
 /** How a run ended as an execution, as run.json records it: the result's ok and execution outcome. */
 interface RecordedOutcome {
@@ -46,6 +82,8 @@ interface Run {
     readonly study?: RunStudyProvenance;
     /** Routes write their evidence files through these and hand them to participants. */
     readonly paths: PreparedRunArtifactPaths;
+    /** The literal values the route scrubs from this run's evidence; a value found later is added here. */
+    readonly secrets: RunSecrets;
     /**
      * Publish an in-progress bundle: run.json, review.json, review.md, events.ndjson and
      * observer/observer-data.json, plus the latest pointer until one pointer write has succeeded,
@@ -74,11 +112,27 @@ interface Run {
      */
     finish(bundle: RunBundle, outcome: FinishOutcome): Promise<FinishedRun>;
 }
+/** A recorded route's run, with the source its bundle records. */
+interface RecordedRun extends Run {
+    /** The package and the project's git state, captured once the run exists, at its createdAt. */
+    readonly source: RunBundle["source"];
+}
 export interface RunScope {
+    /**
+     * Start a recorded route's run from its plan and input: the input's run id or one minted from
+     * `prefix`, the plan's mode, study and warnings, and an Observer that opens when the input says
+     * `open` and renders through the input's `deps.renderObserver`. Then capture the run's source.
+     * The run starts as the form below does.
+     */
+    startRun(plan: StartRunPlan, input: StartRunInput, options: RouteRunOptions): Promise<{
+        ok: true;
+        run: RecordedRun;
+    } | RunIdInUse>;
     /**
      * Create `.humanish/runs/<id>` exclusively, begin status.json and wait for its first write, so
      * a run that got past this point has a status record before any sandbox exists. An id whose
-     * directory exists is refused before any write. A scope starts at most one run.
+     * directory exists is refused before any write. A scope starts at most one run. Preview calls
+     * this form, since it builds its source before the run and mints its own id.
      */
     startRun(options: StartRunOptions): Promise<{
         ok: true;