humanish 0.111.2 → 0.111.4

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

@@ -1,6 +1,7 @@
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { StudyConfig, StudySubjectServe, StudySubjectStateCheckpoint } from "../../study/types.js";
 import type { RunScope } from "../../run/run.js";
+import type { RunSecrets } from "../../run/secrets.js";
 import type { ConcurrentSharedWorldStudyErrorCode, ConcurrentSharedWorldStudyResult, ConcurrentSharedWorldPlaneClass, FinishFacts, LiveParticipants, PlaneContext, PlaneResults, PlaneSelection, SharedWorldRunInput } from "./types.js";
 import type { StudyDeps } from "../../study/study-deps.js";
 import type { SharedWorldPlan } from "../../study/plan-types.js";
@@ -16,7 +17,6 @@ interface AdmittedStudy {
     env: Record<string, string | undefined>;
     descriptor: CuaActorDescriptor;
     planeClass: ConcurrentSharedWorldPlaneClass;
-    runBudget: PlaneContext["runBudget"];
     runSession: PlaneContext["runSession"];
     serve: StudySubjectServe | undefined;
     localTreeRoute: boolean;
@@ -25,8 +25,7 @@ interface AdmittedStudy {
     checkpoints: StudySubjectStateCheckpoint[];
     openaiApiKey: string;
     e2bApiKey: string;
-    knownSecretValues: string[];
-    scrubKnownValues: (text: string) => string;
+    secrets: RunSecrets;
     publicRepo: string;
     hasGithubToken: boolean;
     fail: (code: ConcurrentSharedWorldStudyErrorCode, message: string, actorLabel?: string) => ConcurrentSharedWorldStudyResult;

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/credentials.js

@@ -1,5 +1,18 @@
 import { DEFAULT_RUNTIME_AUTH, E2B_SYSTEM_CA_BUNDLE, OPENAI_EGRESS_PLACEHOLDER, } from "./runtime-auth.js";
 import { TERMINAL_PRODUCT_STUDY_PROVIDER_METADATA } from "./types.js";
+/**
+ * Where the study's runtime auth puts the key, as a sentence for the missing-key refusal. Typed
+ * `unknown` because a config that skipped the planner may hold a mode the type does not list.
+ */
+function keyPlacement(runtimeAuth) {
+    if (runtimeAuth === undefined)
+        return ` \`execution.runtimeAuth\` is unset, so the default ${DEFAULT_RUNTIME_AUTH} keeps the key outside the sandbox in an E2B header transform.`;
+    if (runtimeAuth === "openai-egress")
+        return " `execution.runtimeAuth: openai-egress` keeps the key outside the sandbox in an E2B header transform.";
+    if (runtimeAuth === "openai-env")
+        return " `execution.runtimeAuth: openai-env` passes the key to the codex command only.";
+    return "";
+}
 /**
  * Resolve the runtime key on the host. openai-egress, the default, returns an inert command env
  * while retaining the actual value for the external transform and literal redaction; openai-env
@@ -38,7 +51,7 @@ export function buildRuntimeAuth(args) {
         return {
             ok: false,
             code: "HUMANISH_TERMINAL_RUNTIME_AUTH_MISSING",
-            message: `Live terminal-product studies declare runtimeAuth "${String(args.runtimeAuth)}" and need ${ALLOWED_RUNTIME_KEY_NAMES.join(" or ")} in the environment (pass via --dotenv; the selected auth mode places the value in command-scoped env or an external E2B header transform; the value is never persisted).`,
+            message: `Live terminal-product studies need ${ALLOWED_RUNTIME_KEY_NAMES.join(" or ")} in the environment, and neither is set.${keyPlacement(args.runtimeAuth)} Pass one with --dotenv; the value is never persisted.`,
         };
     }
     const keyValue = args.env[keyName];

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,19 +14,22 @@ 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;
     const { terminalEvents, commandLog, discardedPrefixes } = inputs.recorder;
-    // 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
+    // Prefix reconciliation may cut through a known key. Scrub the known values, as written and in
+    // each encoded form, 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, (text) => inputs.run.secrets.spans(text), 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();
-    const normalizedTranscript = `${normalizeLocalActorTranscript(terminalEvents.map((e) => e.chunk).join(""))}${cut ? `\n[humanish] ${cut.notice}` : ""}`;
+    // Normalizing removes terminal escape sequences, which rejoins a value one of them split, so the
+    // transcript is sanitized again after it.
+    const normalizedTranscript = `${sanitize(normalizeLocalActorTranscript(terminalEvents.map((e) => e.chunk).join("")))}${cut ? `\n[humanish] ${cut.notice}` : ""}`;
     // Parsed from the full stream: usage records arrive once per turn, and the tail
     // would drop all but the last. Records past the cap were kept as they arrived.
     const terminalTokenUsage = parseTerminalTokenUsage([normalizedTranscript, ...(cut?.usage ?? [])].join("\n"));

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.forms(),
+        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

@@ -5,9 +5,11 @@ 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.
+ * `spansOf` finds them in the joined text: RunSecrets.spans, which also finds a value in an
+ * encoded form or split by a terminal escape sequence. Work backwards through the spans 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[], spansOf: (text: string) => ReadonlyArray<readonly [number, number]>, 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;
 /**