humanish 0.110.2 → 0.110.4

package/dist/routes/scripted/route.js

@@ -17,14 +17,13 @@
 import { randomBytes } from "node:crypto";
 import { realpath } from "node:fs/promises";
 import path from "node:path";
-import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
-import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { buildRunSource } from "../../run/bundle.js";
 import { prepareSelectedOutputDirectory } from "../../run/contained-output.js";
-import { runScope } from "../../run/run.js";
+import {} from "../../run/run.js";
+import { admitRoute, completeRefusalAnalysis } from "../../run/route-shell.js";
 import { renderScriptedReviewMarkdown } from "./bundle.js";
-import { injectedBrowser, planScriptedStudy } from "./plan.js";
+import {} from "./plan.js";
 import { finishScriptedRun } from "./result.js";
 import { UnsafeScriptedSessionResultError } from "./session-result.js";
 import { prepareScriptedRun } from "./setup.js";
@@ -32,21 +31,7 @@ import { ScriptedSubject } from "./subject.js";
 import { runScriptedSessions, writeSurfaceTraces } from "./surface-sessions.js";
 import {} from "./types.js";
 import { studyResultIdentity } from "../../run/study-result.js";
-/**
- * The config-taking entry point. It plans, returns a refusal with the envelope the route has always
- * returned at that refusal's stage, and otherwise runs the plan.
- */
-export async function runScriptedBrowserStudy(options) {
-    const { config, dryRun, ...input } = options;
-    // planScriptedStudy makes every configuration refusal, in the order this route always has.
-    const planned = planScriptedStudy(config, {
-        dryRun,
-        injectedBrowser: injectedBrowser(input.deps),
-    });
-    if (planned.ok)
-        return runScriptedPlan(planned.plan, input);
-    return scriptedStudyRefusal(options, planned.refusal);
-}
+import { actorOf } from "../../study/study-fields.js";
 /**
  * A refused scripted study's result, at the refusal's stage: a before-scope refusal has its own field
  * order and no analysis record; the others come after the output directory checks.
@@ -54,7 +39,7 @@ export async function runScriptedBrowserStudy(options) {
 export async function scriptedStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
     const cwd = path.resolve(options.cwd);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     if (refusal.beforeScope)
         return {
             ...studyResultIdentity("scripted", config.id),
@@ -83,35 +68,19 @@ export async function scriptedStudyRefusal(options, refusal) {
         warnings: [],
         error: { code: refusal.code, message: refusal.message },
     };
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+    return completeRefusalAnalysis(refused, config, options);
 }
 /**
  * runStudyWith's step for a scripted plan. It takes no scorer, and its local checks (keys, a browser)
  * run inside the run, so it returns the run.
  */
 export function admitScriptedPlan(plan, input) {
-    return {
-        ok: true,
-        run: async () => ({
-            route: "scripted",
-            result: await runScriptedPlan(plan, input),
-        }),
-    };
-}
-/**
- * Run a scripted plan. The run scope gives a direct library caller the same status-record lifetime
- * the CLI gets: returning from this function finalizes any record the run opened, whichever of its
- * fail-closed exits it took. Each route opens its own scope; `runStudyWith` opens none. Without this a
- * test or an adopter calling the route directly leaves
- * the 5s cadence ticking into a directory something else is deleting, which surfaces as an
- * unrelated ENOTEMPTY.
- */
-export async function runScriptedPlan(plan, input) {
-    const { result, finished } = await runScope((scope) => runScriptedPlanInScope(plan, input, scope));
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
-        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
-        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
+    return admitRoute({
+        route: "scripted",
+        analysis: plan.analysis,
+        input,
+        admit: () => ({ ok: true, admitted: plan }),
+        runInScope: runScriptedPlanInScope,
     });
 }
 async function runScriptedPlanInScope(plan, input, scope) {
@@ -126,6 +95,8 @@ async function runScriptedPlanInScope(plan, input, scope) {
         mintRunId: makeScriptedRunId,
         mode: dryRun ? "dry-run" : "live",
         study: plan.study,
+        // Only a clone subject is served from a sandbox; an app-url run drives a local browser.
+        sandboxes: setup.clone ? undefined : "none",
         renderReview: renderScriptedReviewMarkdown,
         observer: { open: input.open === true, render: setup.deps.renderObserver },
     });
@@ -176,6 +147,7 @@ async function runScriptedPlanInScope(plan, input, scope) {
                 deps: setup.deps,
                 browserCommand: setup.browserCommand,
                 runPaths,
+                onSessionStart: () => run.participantStarted(),
             });
         }
         catch (error) {

package/dist/routes/scripted/surface-sessions.d.ts

@@ -8,6 +8,8 @@ export declare function runScriptedSessions(session: Required<Pick<ScriptedBrows
     deps: StudyDeps;
     browserCommand: string | undefined;
     runPaths: PreparedRunArtifactPaths;
+    /** Called as each surface's session starts, before it can throw or return. */
+    onSessionStart: () => void;
 }): Promise<ScriptedBrowserSessionResult[]>;
 /** Writes each surface's actor-<surface>.json, as the computer-use route writes actor.json. */
 export declare function writeSurfaceTraces(runPaths: PreparedRunArtifactPaths, results: readonly ScriptedBrowserSessionResult[]): Promise<void>;

package/dist/routes/scripted/surface-sessions.js

@@ -7,9 +7,10 @@ import { validateScriptedSessionResult } from "./session-result.js";
 /** One session per surface, in parallel. */
 export function runScriptedSessions(session, run) {
     const { appUrl, evidenceAppUrl, urlPolicy, journey, persona, timeoutMs, artifactRoot } = session;
-    const { surfaces, deps, browserCommand, runPaths } = run;
+    const { surfaces, deps, browserCommand, runPaths, onSessionStart } = run;
     const runSession = deps.runScriptedSession;
     return Promise.all(surfaces.map((surface) => {
+        onSessionStart();
         const sessionOptions = {
             appUrl,
             evidenceAppUrl,

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

@@ -1,23 +1,18 @@
 import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
 import type { StudyEvent } from "../../study/run-study-events.js";
 import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
-import type { StudyConfig } from "../../study/types.js";
 import type { ObserverResult } from "../../observer/render.js";
 import type { RunSubjectProvenance } from "../../run/bundle.js";
 import type { StudyDeps } from "../../study/study-deps.js";
 import type { RunStudyHomes } from "../../study/run-study-homes.js";
 import { type StudyResultIdentity } from "../../run/study-result.js";
 /** What a scripted run takes besides its plan. The plan carries the config, dry run and study. */
-export type ScriptedRunInput = Omit<RunScriptedBrowserStudyOptions, "config" | "dryRun">;
-export interface RunScriptedBrowserStudyOptions {
+export interface ScriptedRunInput {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
     /** Reports the analysis window to onEvent; built by normalizeRunStudyOptions. */
     emit?: (event: StudyEvent) => void;
     cwd: string;
-    config: StudyConfig;
-    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
-    dryRun: boolean;
     open?: boolean;
     runId?: string;
     /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */

package/dist/routes/shared-world/participant-specs.js

@@ -167,7 +167,11 @@ export function participantRunDeps(ctx, live, scrubKnownValues) {
         studyCwd: ctx.cwd,
         redactScreenshots: ctx.redactScreenshots,
         scrubKnownValues,
-        runSession: ctx.runSession,
+        // A session that throws returns no trace; the run still records that it started.
+        runSession: (options) => {
+            ctx.run.participantStarted();
+            return ctx.runSession(options);
+        },
         // A local-agent brain runs each participant on the operator's signed-in agent, as on computer
         // use.
         brain: ctx.plan.brain,

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

@@ -6,12 +6,13 @@ import { DEFAULT_OPENAI_CU_MODEL } from "../../actors/computer-use/openai-provid
 import { studyUrlCredentialReason } from "../../study/url-credentials.js";
 import { actorRegistry, isCuaActorDescriptor, } from "../../actors/registry.js";
 import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { brainOf, capsOf, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
+import { brainOf, planCaps, desktopRequirements, isNonEmpty, planBase, } from "../../study/plan-base.js";
 import { sharedWorldParticipants } from "../../study/plan-participants.js";
 import { PUBLIC_TARGET_OWNER_PATTERN } from "../../study/parse/subject.js";
 import { REPO_SLUG_PATTERN } from "../../study/parse/values.js";
 import { concurrentSharedWorldValidationReason, desktopMediaValidationReason, externalPublicSharedWorldValidationReason, outputTokenLimitValidationReason, receivingEmailValidationReason, scenarioCapsValidationReason, taskProtocolValidationReason, } from "../../study/validation.js";
 import { MODEL_RATES, unpricedCapMessage } from "../../run/pricing.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /** The registered descriptor for a planned actor; planSharedWorldStudy checked the registry. */
 export function sharedWorldDescriptorOf(actorType) {
     const descriptor = actorRegistry[actorType];
@@ -38,7 +39,7 @@ export function planSharedWorldStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isCuaActorDescriptor(descriptor))
         return refuse("HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered computer-use actor.`);
@@ -59,11 +60,11 @@ export function planSharedWorldStudy(config, input) {
             : concurrentSharedWorldValidationReason(config));
     if (invalidReason)
         return refuse(invalid, invalidReason, actor);
-    if (config.actors[0]?.maxOutputTokens !== undefined && input.hasRunSession === true)
+    if (actorOf(config)?.maxOutputTokens !== undefined && input.hasRunSession === true)
         return refuse(invalid, "maxOutputTokens cannot be enforced by a custom runSession.", actor);
-    const caps = config.execution?.caps;
+    const caps = capsOf(config, "shared-world");
     if (!input.dryRun && (caps?.maxUsd !== undefined || caps?.maxTotalUsd !== undefined)) {
-        const model = (config.actors[0]?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
+        const model = (actorOf(config)?.model ?? DEFAULT_OPENAI_CU_MODEL).trim().toLowerCase();
         if (!MODEL_RATES[model])
             return refuse("HUMANISH_SHARED_WORLD_UNPRICED_CAP", unpricedCapMessage(model), actor);
     }
@@ -106,7 +107,7 @@ export function planSharedWorldStudy(config, input) {
                 ? {}
                 : { sessionTimeoutMs: config.execution.timeoutMs }),
             brain,
-            caps: capsOf(config),
+            caps: planCaps(config, "shared-world"),
             requirements: base.dryRun
                 ? []
                 : [

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

@@ -1,21 +1,15 @@
+import { type RefusedStudy } from "../../run/route-shell.js";
 import { type SharedWorldRefusal } from "./plan.js";
 import type { SharedWorldPlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
 import type { StudyConfig } from "../../study/types.js";
-import { type ConcurrentSharedWorldStudyResult, type SharedWorldRunInput, type RunConcurrentSharedWorldStudyOptions } from "./types.js";
-/**
- * The library entry for a shared-world study. It plans the config with planSharedWorldStudy and runs
- * the plan with runSharedWorldPlan, whose run scope and withTransientCommsSecrets wrapper cover the
- * run and its analysis.
- */
-export declare function runConcurrentSharedWorld(options: RunConcurrentSharedWorldStudyOptions): Promise<ConcurrentSharedWorldStudyResult>;
+import { type ConcurrentSharedWorldStudyResult, type SharedWorldRunInput } from "./types.js";
 /** A refused shared-world study's result: the route's envelope, and a refusal's analysis record. */
-export declare function sharedWorldStudyRefusal(options: RunConcurrentSharedWorldStudyOptions, refusal: SharedWorldRefusal): Promise<ConcurrentSharedWorldStudyResult>;
+export declare function sharedWorldStudyRefusal(options: SharedWorldRunInput & RefusedStudy, refusal: SharedWorldRefusal): Promise<ConcurrentSharedWorldStudyResult>;
 /**
  * runStudyWith's step for a shared-world plan. It runs a live plan's local checks (the keys, a local
  * agent's sign-in and the subject env) before any run scope opens, so the CLI can present their refusal before it loads a
- * declared scorer, and returns the run that continues from them with that scorer.
+ * declared scorer, and returns the run that continues from them with that scorer. The run and its
+ * analysis share one scope for the email secrets it registers.
  */
 export declare function admitSharedWorldPlan(plan: SharedWorldPlan, input: SharedWorldRunInput, config: StudyConfig): Promise<AdmittedPlan<"shared-world">>;
-/** Run a shared-world plan: its local checks, then the run. */
-export declare function runSharedWorldPlan(plan: SharedWorldPlan, input: SharedWorldRunInput, config: StudyConfig): Promise<ConcurrentSharedWorldStudyResult>;

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

@@ -34,15 +34,13 @@
 // gate; humanish cannot tell synthetic from real data, so it makes no claim about real data.
 import path from "node:path";
 import { missingKeys, missingSubjectEnv } from "../../study/requirements.js";
-import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
-import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
 import { scrubLiterals } from "../../evidence/redaction.js";
 import { describeMissingKeys } from "../../keys/key-resolution.js";
-import { withTransientCommsSecrets } from "../../run/transient-comms-secrets.js";
-import { runScope } from "../../run/run.js";
+import {} from "../../run/run.js";
+import { admitRoute, completeRefusalAnalysis, } from "../../run/route-shell.js";
 import { makeCuaRunBudget } from "../computer-use/participant-model.js";
 import { runExternalPublicPlane } from "./external-public.js";
-import { planSharedWorldStudy, sharedWorldDescriptorOf } from "./plan.js";
+import { sharedWorldDescriptorOf } from "./plan.js";
 import { localAgentRefusal } from "../../actors/local-agent/readiness.js";
 import { runProvisionedPlane } from "./provisioned.js";
 import { concurrentStudyFailure, finishConcurrentRun } from "./result.js";
@@ -50,7 +48,7 @@ import { prepareConcurrentRun } from "./setup.js";
 import { browserRouteScorer } from "../../study/adapter-scorer-loader.js";
 import { withLateScorer } from "../../study/route-inputs.js";
 import {} from "./types.js";
-import { rosterOf } from "../../study/parse/actors.js";
+import { actorOf, participantList } from "../../study/study-fields.js";
 /** The shared-world code for each local-agent refusal, kind for kind with computer-use. */
 const LOCAL_AGENT_REFUSAL_CODES = {
     "agent-missing": "HUMANISH_SHARED_WORLD_AGENT_MISSING",
@@ -58,30 +56,14 @@ const LOCAL_AGENT_REFUSAL_CODES = {
     unsupported: "HUMANISH_SHARED_WORLD_ACTOR_UNSUPPORTED",
     "unpriced-cap": "HUMANISH_SHARED_WORLD_UNPRICED_CAP",
 };
-/**
- * The library entry for a shared-world study. It plans the config with planSharedWorldStudy and runs
- * the plan with runSharedWorldPlan, whose run scope and withTransientCommsSecrets wrapper cover the
- * run and its analysis.
- */
-export async function runConcurrentSharedWorld(options) {
-    const { config, dryRun, ...input } = options;
-    // planSharedWorldStudy makes every configuration refusal, in the order this route always has.
-    const planned = planSharedWorldStudy(config, {
-        dryRun,
-        hasRunSession: input.deps?.runSession !== undefined,
-    });
-    if (planned.ok)
-        return runSharedWorldPlan(planned.plan, input, config);
-    return sharedWorldStudyRefusal(options, planned.refusal);
-}
 /** A refused shared-world study's result: the route's envelope, and a refusal's analysis record. */
 export function sharedWorldStudyRefusal(options, refusal) {
     const { config, dryRun } = options;
-    const declared = rosterOf(config.actors[0]) ?? [];
+    const declared = participantList(config) ?? [];
     const fail = concurrentStudyFailure({
         cwd: path.resolve(options.cwd),
         studyId: config.id,
-        actor: config.actors[0]?.type ?? "",
+        actor: actorOf(config)?.type ?? "",
         participantCount: declared.length,
         // The parser fills concurrency for multi-participant studies, so this fallback serves only
         // library callers: every declared participant runs at once unless the author declared a cap.
@@ -89,42 +71,38 @@ export function sharedWorldStudyRefusal(options, refusal) {
         dryRun,
         runId: options.runId,
     });
-    // A refusal starts no run, so a declared or default analysis is recorded as skipped.
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(fail(refusal.code, refusal.message, refusal.actor), undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
+    return completeRefusalAnalysis(fail(refusal.code, refusal.message, refusal.actor), config, options);
 }
 /**
  * runStudyWith's step for a shared-world plan. It runs a live plan's local checks (the keys, a local
  * agent's sign-in and the subject env) before any run scope opens, so the CLI can present their refusal before it loads a
- * declared scorer, and returns the run that continues from them with that scorer.
+ * declared scorer, and returns the run that continues from them with that scorer. The run and its
+ * analysis share one scope for the email secrets it registers.
  */
-export async function admitSharedWorldPlan(plan, input, config) {
-    const refused = await admitSharedWorldRun(plan, input);
-    if (refused)
-        return { ok: false, outcome: sharedWorldOutcome(refused) };
-    return {
-        ok: true,
-        run: async (scorer) => sharedWorldOutcome(await runAdmittedSharedWorldRun(plan, withLateScorer(input, scorer, browserRouteScorer), config)),
-    };
-}
-function sharedWorldOutcome(result) {
-    return { route: "shared-world", result };
-}
-/** Run a shared-world plan: its local checks, then the run. */
-export async function runSharedWorldPlan(plan, input, config) {
-    const refused = await admitSharedWorldRun(plan, input);
-    return refused ?? runAdmittedSharedWorldRun(plan, input, config);
+export function admitSharedWorldPlan(plan, input, config) {
+    return admitRoute({
+        route: "shared-world",
+        analysis: plan.analysis,
+        input,
+        admit: () => admitSharedWorldRun(plan, input),
+        withScorer: (base, scorer) => withLateScorer(base, scorer, browserRouteScorer),
+        runInScope: (_admitted, running, scope) => runPlanInScope(plan, running, config, scope),
+        commsSecrets: true,
+    });
 }
 /**
  * A live plan's local checks, made outside any run scope: the keys, a local agent's sign-in, then
- * the subject env. A refusal is the result runSharedWorldPlan returns for it, with the analysis
- * record of a run that never started.
+ * the subject env.
  */
 async function admitSharedWorldRun(plan, input) {
+    const admitted = { ok: true, admitted: undefined };
     if (plan.dryRun)
-        return undefined;
+        return admitted;
     const env = input.env ?? process.env;
-    const fail = (code, message) => completeSharedWorldAnalysis(plan, input, sharedWorldFailure(plan, input)(code, message, sharedWorldDescriptorOf(plan.actor).id), undefined);
+    const fail = (code, message) => ({
+        ok: false,
+        result: sharedWorldFailure(plan, input)(code, message, sharedWorldDescriptorOf(plan.actor).id),
+    });
     // The plan lists OPENAI_API_KEY for an openai brain's participants and the external-public
     // plane's lobby-code reader; a local-agent brain's participants run on the operator's signed-in
     // agent instead.
@@ -143,24 +121,7 @@ async function admitSharedWorldRun(plan, input) {
     if (unsetSubjectEnv.length > 0) {
         return fail("HUMANISH_SHARED_WORLD_SUBJECT_ENV_MISSING", `subject.env declares ${unsetSubjectEnv.join(", ")} but the environment does not provide ${unsetSubjectEnv.length === 1 ? "it" : "them"} (pass via --dotenv; values are never persisted).`);
     }
-    return undefined;
-}
-/**
- * Runs an admitted plan in its own run scope, then its automatic analysis. The
- * withTransientCommsSecrets wrapper scopes any email secret the run registers to this run and its
- * analysis.
- */
-function runAdmittedSharedWorldRun(plan, input, config) {
-    return withTransientCommsSecrets(async () => {
-        const { result, finished } = await runScope((scope) => runPlanInScope(plan, input, config, scope));
-        return completeSharedWorldAnalysis(plan, input, result, finished);
-    });
-}
-function completeSharedWorldAnalysis(plan, input, result, finished) {
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
-        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
-        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
-    });
+    return admitted;
 }
 /** The route's envelope for a run that stops before its bundle. */
 function sharedWorldFailure(plan, input) {

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

@@ -24,13 +24,11 @@ export declare const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA: {
     readonly tool: "humanish";
 };
 export declare const CONCURRENT_ATTRIBUTION_LIMITS: readonly ["concurrent", "best-effort-causal-attribution", "non-deterministic-shared-state", "window-and-snapshot-granularity", "contention-observed-not-proven-safe", "state-change-not-isolated-to-actors"];
-export interface RunConcurrentSharedWorldStudyOptions {
+/** What a shared-world run takes besides its plan. The plan carries the config, dry run and study. */
+export interface SharedWorldRunInput {
     /** Cancels post-run analysis only. */
     analysisSignal?: AbortSignal;
     cwd: string;
-    config: StudyConfig;
-    /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
-    dryRun: boolean;
     open?: boolean;
     runId?: string;
     onObserverReady?: (observer: ObserverResult & {
@@ -56,8 +54,6 @@ export interface RunConcurrentSharedWorldStudyOptions {
      *  core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
-/** What a shared-world run takes besides its plan. The plan carries the config, dry run and study. */
-export type SharedWorldRunInput = Omit<RunConcurrentSharedWorldStudyOptions, "config" | "dryRun">;
 export type ConcurrentSharedWorldStudyErrorCode = "HUMANISH_STUDY_ANALYSIS_INVALID" | "HUMANISH_STUDY_TASKS_UNSUPPORTED" | "HUMANISH_STUDY_OPTION_UNSUPPORTED" | "HUMANISH_STUDY_V2_UNSUPPORTED" | "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"

package/dist/routes/terminal/plan.js

@@ -13,6 +13,7 @@ import { NODE_BOOTSTRAP_TIMEOUT_MS } from "../../subject/node-bootstrap.js";
 import { terminalSandboxTimeoutMs } from "./lifetime.js";
 import { isExactRuntimeVersion, TERMINAL_RUNTIME_VERSION_TIMEOUT_MS } from "./runtime.js";
 import { PRODUCT_SETUP_TIMEOUT_MS, TERMINAL_SANDBOX_TIMEOUT_BUFFER_MS, } from "./types.js";
+import { actorOf, capsOf } from "../../study/study-fields.js";
 /**
  * Plan a terminal-product study. It is called for any config handed to the terminal runner, not
  * only one routeOf sends here, so a config for another route gets this route's refusal.
@@ -40,12 +41,12 @@ export function planTerminalStudy(config, input) {
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return refuse("HUMANISH_STUDY_TASKS_UNSUPPORTED", tasksReason);
-    const actorType = config.actors[0]?.type ?? "";
+    const actorType = actorOf(config)?.type ?? "";
     const descriptor = actorRegistry[actorType];
     if (!descriptor || !isTerminalActorDescriptor(descriptor))
         return refuse("HUMANISH_TERMINAL_ACTOR_UNSUPPORTED", `actor.type "${actorType}" is not a registered terminal actor.`);
     const runtimeVersion = config.execution?.runtime?.version;
-    const actor = config.actors[0];
+    const actor = actorOf(config);
     if ((config.execution?.runtime !== undefined && !isExactRuntimeVersion(runtimeVersion)) ||
         (actor?.model !== undefined &&
             (typeof actor.model !== "string" || actor.model.trim().length === 0)) ||
@@ -83,7 +84,7 @@ export function planTerminalStudy(config, input) {
         ...(egressAllow === undefined ? {} : { egressAllow }),
         ...(stdin === undefined ? {} : { stdin }),
     };
-    const caps = config.scenario?.caps;
+    const caps = capsOf(config, "terminal");
     if (input.dryRun)
         return { ok: true, plan: { ...shared, dryRun: true, ...(caps ? { caps } : {}) } };
     // The live route injects the runtime key into one command only, and only a registered actor

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

@@ -1,20 +1,10 @@
+import { type RefusedStudy } from "../../run/route-shell.js";
 import { type TerminalRefusal } from "./plan.js";
 import type { TerminalPlan } from "../../study/plan-types.js";
 import type { AdmittedPlan } from "../../run-study.js";
-import { type RunTerminalProductStudyOptions, type TerminalProductStudyResult, type TerminalRunInput } from "./types.js";
-/**
- * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
- * record the route has always returned, and otherwise runs the plan.
- */
-export declare function runTerminalProductStudy(options: RunTerminalProductStudyOptions): Promise<TerminalProductStudyResult>;
+import { type TerminalProductStudyResult, type TerminalRunInput } from "./types.js";
 /** A refused terminal study's result: the route's envelope, and the analysis record a refusal gets. */
-export declare function terminalStudyRefusal(options: RunTerminalProductStudyOptions, refusal: TerminalRefusal): Promise<TerminalProductStudyResult>;
-/**
- * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
- * gets: whichever of its fail-closed exits the run takes, the run it started is closed, and only a
- * run that published its final bundle reaches automatic analysis.
- */
-export declare function runTerminalPlan(plan: TerminalPlan, input: TerminalRunInput): Promise<TerminalProductStudyResult>;
+export declare function terminalStudyRefusal(options: TerminalRunInput & RefusedStudy, refusal: TerminalRefusal): Promise<TerminalProductStudyResult>;
 /**
  * runStudyWith's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
  * before any run scope opens, so the CLI can present their refusal before it loads a declared

package/dist/routes/terminal/route.js

@@ -44,31 +44,17 @@
 //      humanish never calls Sandbox.list to prove cleanup, so a shared operator key never reaches a
 //      sandbox it did not create. A live run that cannot prove teardown fails closed.
 //      Enforced in sandbox.ts.
-import { resolveAutomaticAnalysis } from "../../analysis/automatic-config.js";
-import { completeAutomaticAnalysis } from "../../analysis/automatic-completion.js";
 import path from "node:path";
-import { runScope } from "../../run/run.js";
-import { planTerminalStudy } from "./plan.js";
+import {} from "../../run/run.js";
+import { admitRoute, completeRefusalAnalysis, } from "../../run/route-shell.js";
+import {} from "./plan.js";
 import { runDryTerminalStudy } from "./dry-run.js";
 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";
-/**
- * The config-taking entry point. It plans, returns a refusal with the same envelope and analysis
- * record the route has always returned, and otherwise runs the plan.
- */
-export async function runTerminalProductStudy(options) {
-    const { config, dryRun, ...input } = options;
-    const planned = planTerminalStudy(config, {
-        dryRun,
-        hasCostProbe: input.deps?.costProbe !== undefined,
-    });
-    if (planned.ok)
-        return runTerminalPlan(planned.plan, input);
-    return terminalStudyRefusal(options, planned.refusal);
-}
+import { actorOf } from "../../study/study-fields.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;
@@ -76,67 +62,42 @@ export function terminalStudyRefusal(options, refusal) {
         ...studyResultIdentity("terminal", config.id),
         ok: false,
         cwd: path.resolve(options.cwd),
-        actor: refusal.actor ?? config.actors[0]?.type ?? "",
+        actor: refusal.actor ?? actorOf(config)?.type ?? "",
         product: config.subject.product?.name ?? "",
         dryRun,
         runId: options.runId ?? "not-created",
         warnings: [],
         error: { code: refusal.code, message: refusal.message },
     };
-    // A refusal starts no run, so a declared or default analysis is recorded as skipped.
-    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
-    return completeAutomaticAnalysis(refused, undefined, analysis.ok ? analysis.config : undefined, options, { trigger: config.review?.analysis === undefined ? "default" : "explicit" });
-}
-/**
- * Run a terminal plan. The run scope gives a direct library caller the same run lifetime the CLI
- * gets: whichever of its fail-closed exits the run takes, the run it started is closed, and only a
- * run that published its final bundle reaches automatic analysis.
- */
-export async function runTerminalPlan(plan, input) {
-    const admission = await admitTerminalRun(plan, input);
-    return admission.ok ? runAdmittedTerminalRun(admission.admitted, input) : admission.result;
+    return completeRefusalAnalysis(refused, config, options);
 }
 /**
  * runStudyWith's step for a terminal plan. It runs a live plan's local checks (checkLiveTerminalMachine)
  * before any run scope opens, so the CLI can present their refusal before it loads a declared
  * scorer, and returns the run that continues from them with that scorer.
  */
-export async function admitTerminalPlan(plan, input) {
-    const admission = await admitTerminalRun(plan, input);
-    if (!admission.ok)
-        return { ok: false, outcome: terminalOutcome(admission.result) };
-    return {
-        ok: true,
-        run: async (scorer) => terminalOutcome(await runAdmittedTerminalRun(admission.admitted, withLateScorer(input, scorer, terminalRouteScorer))),
-    };
-}
-function terminalOutcome(result) {
-    return { route: "terminal", result };
+export function admitTerminalPlan(plan, input) {
+    return admitRoute({
+        route: "terminal",
+        analysis: plan.analysis,
+        input,
+        admit: () => admitTerminalRun(plan, input),
+        withScorer: (base, scorer) => withLateScorer(base, scorer, terminalRouteScorer),
+        runInScope: runTerminalPlanInScope,
+    });
 }
-/**
- * A live plan's local checks, made outside any run scope. A refusal is the result runTerminalPlan
- * returns for it, with the analysis record of a run that never started.
- */
-async function admitTerminalRun(plan, input) {
+/** A live plan's local checks, made outside any run scope. */
+function admitTerminalRun(plan, input) {
     const warnings = [];
     if (plan.dryRun)
         return { ok: true, admitted: { plan, warnings } };
     const checked = checkLiveTerminalMachine(plan, input, warnings);
     if (checked.ok)
         return { ok: true, admitted: { plan, warnings, runtimeEnv: checked.runtimeEnv } };
-    const refused = terminalFailure(plan, input, warnings)(checked.code, checked.message);
-    return { ok: false, result: await completeTerminalAnalysis(plan, input, refused, undefined) };
-}
-/** Runs an admitted plan in its own run scope, then its automatic analysis. */
-async function runAdmittedTerminalRun(admitted, input) {
-    const { result, finished } = await runScope((scope) => runTerminalPlanInScope(admitted, input, scope));
-    return completeTerminalAnalysis(admitted.plan, input, result, finished);
-}
-function completeTerminalAnalysis(plan, input, result, finished) {
-    return completeAutomaticAnalysis(result, finished, plan.analysis?.config, input, {
-        ...(plan.analysis === undefined ? {} : { trigger: plan.analysis.trigger }),
-        preferLargerOutput: plan.analysis?.preferLargerOutput === true,
-    });
+    return {
+        ok: false,
+        result: terminalFailure(plan, input, warnings)(checked.code, checked.message),
+    };
 }
 /** The route's envelope for a run that stops before its bundle. */
 function terminalFailure(plan, input, warnings) {

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

@@ -13,9 +13,8 @@ export declare function checkLiveTerminalMachine(plan: LiveTerminalPlan, input:
     readonly message: string;
 };
 /**
- * The live in-sandbox agent session orchestrator (mirror of runCuaActorStudy's E2B branch). Enforces
- * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
- * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * The 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,
  * the redacted terminal event stream + normalized transcript, the agent report, and the
  * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
  */

package/dist/routes/terminal/session.js

@@ -38,9 +38,8 @@ export function checkLiveTerminalMachine(plan, input, warnings) {
     return { ok: true, runtimeEnv };
 }
 /**
- * The live in-sandbox agent session orchestrator (mirror of runCuaActorStudy's E2B branch). Enforces
- * the 8-point safety contract by construction; fails closed before any sandbox/key/spend on any
- * precondition miss. Persists the substrate-lifecycle/command-log/interventions/cleanup ledgers,
+ * The 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,
  * the redacted terminal event stream + normalized transcript, the agent report, and the
  * provider-neutral actor trace; tears the sandbox down in a finally and proves the teardown.
  */
@@ -112,6 +111,7 @@ export async function runLiveTerminalSession(args) {
         if ((await session.bootstrap()) &&
             (await session.verifyRuntimeVersion()) &&
             (await session.prepareProduct())) {
+            run.participantStarted();
             await session.execCodex();
         }
     }