humanish 0.111.2 → 0.111.3

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;

package/dist/run/run.js

@@ -2,16 +2,18 @@
 // token that lets the Observer and automatic analysis read it. Routes build bundles and write
 // their own evidence files; this module owns when the run starts, how it is published, and how it
 // is closed on every exit.
+import { randomBytes } from "node:crypto";
 import { redactText } from "../evidence/redaction.js";
 import { buildObserverData } from "../observer/data.js";
 import { renderObserver } from "../observer/render.js";
-import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, } from "./bundle.js";
+import { RUN_BUNDLE_FILE, PUBLIC_TARGET_CWD, buildRunSource, } from "./bundle.js";
 import { judgeExecution, } from "./judge.js";
 import {} from "./results.js";
 import { createRunArtifactPaths, validatePreparedRunArtifactPaths, } from "./paths.js";
 import { registerActiveRun } from "./active-runs.js";
 import { writeContainedOutputFile, writePreparedRunLatestPointer } from "./contained-output.js";
 import { scrubRunSandboxIds, withPublicSandboxIds } from "./sandbox-ids.js";
+import { RunSecrets } from "./secrets.js";
 import { beginRunStatus, runStatusOutcome, } from "./status.js";
 /** An entry point called in a state that does not admit it. */
 class RunLifecycleError extends Error {
@@ -239,7 +241,7 @@ export async function runScope(fn) {
         return operation;
     };
     const refuse = (message) => Promise.reject(new RunLifecycleError(message));
-    const startRun = (options) => {
+    const startRunWith = (options) => {
         if (closed)
             return refuse("The run scope has closed.");
         if (started)
@@ -277,6 +279,9 @@ export async function runScope(fn) {
             return { ok: true, run: run.run };
         })());
     };
+    function startRun(...args) {
+        return args.length === 1 ? startRunWith(args[0]) : startRecordedRun(startRunWith, ...args);
+    }
     const openRun = (options, runId, paths, runStatus) => {
         const now = options.now ?? Date.now;
         const createdAt = new Date(now()).toISOString();
@@ -301,6 +306,7 @@ export async function runScope(fn) {
             mode: options.mode,
             ...(options.study === undefined ? {} : { study: options.study }),
             paths,
+            secrets: options.secrets ?? new RunSecrets([]),
             participantStarted() {
                 participantsRan = true;
             },
@@ -348,3 +354,33 @@ export async function runScope(fn) {
     }
     return { result: outcome.result, finished };
 }
+/** Start a recorded route's run through `start`, the scope's own form, then capture its source. */
+async function startRecordedRun(start, plan, input, route) {
+    const started = await start({
+        cwd: route.cwd,
+        runId: input.runId,
+        mintRunId: () => mintRunId(route.prefix),
+        mode: plan.dryRun ? "dry-run" : "live",
+        study: plan.study,
+        warnings: plan.warnings,
+        sandboxes: route.sandboxes,
+        renderReview: route.renderReview,
+        observer: { open: input.open === true, render: input.deps?.renderObserver },
+        now: route.now,
+        secrets: route.secrets,
+    });
+    if (!started.ok)
+        return started;
+    const source = await buildRunSource({
+        cwd: route.cwd,
+        capturedAt: started.run.createdAt,
+        humanishSource: "present",
+        packageName: "humanish",
+    });
+    return { ok: true, run: { ...started.run, source } };
+}
+/** `<prefix>-<wall-clock time, with : and . as ->-<8 hex>`. */
+function mintRunId(prefix) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return `${prefix}-${stamp}-${randomBytes(4).toString("hex")}`;
+}

package/dist/run/secrets.d.ts

@@ -0,0 +1,22 @@
+/** Each route's seed list, marker and floor are its own; the defaults are what most routes use. */
+interface RunSecretsOptions {
+    /** The text that replaces each value. */
+    readonly marker?: string;
+    /** The shortest value scrubbed. A shorter value is ordinary text often enough to leave alone. */
+    readonly minLength?: number;
+}
+export declare class RunSecrets {
+    #private;
+    /**
+     * Replaces every held value with the marker. It reads the values on each call, so a value added
+     * after the scrub was handed to a participant or a subject is scrubbed from then on.
+     */
+    readonly scrub: (text: string) => string;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed: readonly string[], options?: RunSecretsOptions);
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values: readonly string[]): void;
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values(): readonly string[];
+}
+export {};

package/dist/run/secrets.js

@@ -0,0 +1,33 @@
+// The literal values one run scrubs from what it writes: the provider keys and subject env values
+// its route reads, and the values the run provisions while it runs, such as the addresses email
+// receiving registers. These have no secret shape for pattern redaction to find, so each is
+// replaced as written; redactText runs after the scrub and finds secrets by shape.
+import { scrubLiterals } from "../evidence/redaction.js";
+export class RunSecrets {
+    // Private fields stay out of JSON.stringify and object spread, so a Run that reaches a writer
+    // whole cannot carry the values with it.
+    #held;
+    #minLength;
+    /**
+     * Replaces every held value with the marker. It reads the values on each call, so a value added
+     * after the scrub was handed to a participant or a subject is scrubbed from then on.
+     */
+    scrub;
+    /** `seed` keeps its order; values shorter than the floor are dropped. */
+    constructor(seed, options = {}) {
+        // An empty value would match between every character.
+        this.#minLength = Math.max(1, options.minLength ?? 4);
+        this.#held = seed.filter((value) => value.length >= this.#minLength);
+        this.scrub = scrubLiterals(this.#held, options.marker);
+    }
+    /** Holds each value the run learns while it runs, unless it is under the floor or already held. */
+    add(values) {
+        for (const value of values)
+            if (value.length >= this.#minLength && !this.#held.includes(value))
+                this.#held.push(value);
+    }
+    /** The held values, seed first, in one array that later `add` calls extend. */
+    values() {
+        return this.#held;
+    }
+}

package/dist/run/study-result.d.ts

@@ -7,5 +7,39 @@ export interface StudyResultIdentity<R extends string> {
     /** The study's `id`. */
     studyId: string;
 }
+/**
+ * The error codes every recorded route's result can carry besides its own: a study, option or
+ * analysis refusal from before the route's checks, and a run id that is already taken. Each route's
+ * error-code union is this set plus the codes named for that route.
+ */
+export type StudyResultErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "HUMANISH_STUDY_INVALID" | "HUMANISH_RUN_ID_IN_USE";
 /** The identity fields for a result of route `route` from the study `studyId`. */
 export declare function studyResultIdentity<R extends string>(route: R, studyId: string): StudyResultIdentity<R>;
+/** What every refused study's result carries besides its identity and its route's own fields. */
+export interface RefusalBase<C extends string> {
+    /** The study's `id`. */
+    studyId: string;
+    cwd: string;
+    /** The caller's warnings array, kept by reference so warnings added later still show. Empty when omitted. */
+    warnings?: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+}
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export declare function refusedResult<R extends string, C extends string, F extends object>(route: R, base: RefusalBase<C>, fields: F): StudyResultIdentity<R> & {
+    ok: false;
+    cwd: string;
+} & F & {
+    warnings: string[];
+    error: {
+        code: C;
+        message: string;
+    };
+};

package/dist/run/study-result.js

@@ -7,3 +7,19 @@ export const STUDY_RESULT_SCHEMA = "humanish.study-result.v1";
 export function studyResultIdentity(route, studyId) {
     return { schema: STUDY_RESULT_SCHEMA, route, studyId };
 }
+/**
+ * A refused study's result on route `route`: its identity, `ok: false` and `cwd`, then `fields`
+ * in the caller's order, then `warnings` and `error`. A result is written as JSON, so the key order
+ * is part of the output; a site whose order differs spreads its remaining fields after this. The
+ * caller keeps runId, actor, dryRun and the route's fields, whose values and order differ by site.
+ */
+export function refusedResult(route, base, fields) {
+    return {
+        ...studyResultIdentity(route, base.studyId),
+        ok: false,
+        cwd: base.cwd,
+        ...fields,
+        warnings: base.warnings ?? [],
+        error: base.error,
+    };
+}