humanish 0.106.0 → 0.107.0

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

@@ -1,22 +1,19 @@
+import type { LabDeps } from "../../lab/lab-deps.js";
+import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
 import type { SharedWorldJudgment } from "../../run/judge.js";
-import type { CuaActorSessionOptions } from "../../actors/computer-use/actor.js";
-import type { CuaLoopResult } from "../../actors/computer-use/loop.js";
-import type { BrowserLabAdapterHooks } from "../../lab/adapter-extension.js";
-import type { SubjectPhaseEvent } from "../../subject/steps.js";
-import type { DetachedTimers } from "../../substrates/detached.js";
-import type { E2BDesktopModule, E2BDesktopSandbox } from "../../substrates/e2b/sdk.js";
-import type { AutomaticAnalysisHooks, AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
+import type { BrowserScorer } from "../../lab/adapter-extension.js";
+import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
 import type { CuaActorDescriptor } from "../../actors/registry.js";
 import type { CommsReceivingRun } from "../../comms/receiving.js";
 import type { LabCommsEmail, LabCommsExternal, LabConfig } from "../../lab/types.js";
 import type { DesktopResourceObservation } from "../../substrates/e2b/desktop-resources.js";
-import type { ObserverResult, renderObserver } from "../../observer/render.js";
+import type { ObserverResult } from "../../observer/render.js";
 import type { ObserverRuntimeStreamUrl } from "../../observer/run-routes.js";
-import type { RunBundle, RunScorerProvenance, RunSubjectProvenance, RunSubjectStateStepRecord } from "../../run/bundle.js";
+import type { BundleRun, RunBundle, RunScorerProvenance, RunSubjectProvenance, RunSubjectStateStepRecord } from "../../run/bundle.js";
 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 { RunLabProvenance } from "../../run/status.js";
 import type { LiveTraceFlush } from "../computer-use/live-flush.js";
 import type { CuaParticipantDeps, DesktopParticipantRun, CuaRunBudget, ParticipantRunOutcome } from "../computer-use/types.js";
 import type { ProvisionedPlaneSetup } from "./provisioned.js";
@@ -28,9 +25,8 @@ export declare const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA: {
 };
 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 RunConcurrentSharedWorldLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
+    /** Cancels post-run analysis only. */
+    analysisSignal?: AbortSignal;
     cwd: string;
     config: LabConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
@@ -40,27 +36,44 @@ export interface RunConcurrentSharedWorldLabOptions {
     onObserverReady?: (observer: ObserverResult & {
         ok: true;
     }) => Promise<void> | void;
-    hooks?: SharedWorldLabHooks;
-    /** Present only when the browser-route scorer hooks were CONFIG-DECLARED and loaded by the CLI
-     *  (#316); core-stamped onto the bundle as evidence. Absent for library callers. */
+    /** Keys and subject env for the run. Defaults to process.env. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /**
+     * Runs after a sandbox exists and before anything is provisioned on it: the provisioned plane's
+     * subject sandbox, then each seat's desktop. The external-public plane has seats only.
+     */
+    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    /** Awaited after a participant's live stream starts, and again after its sandbox is gone. */
+    onStream?: NonNullable<RunLabHomes["onStream"]>;
+    /** Reports subject phases to onEvent; built by normalizeRunLabOptions. */
+    emit?: (event: LabEvent) => void;
+    /** Test seams. */
+    deps?: LabDeps;
+    /** Scores the assembled evidence: `RunLabOptions.scorer`, or the scorer the CLI loads. */
+    scorer?: BrowserScorer;
+    /** Present only when the scorer was CONFIG-DECLARED and loaded by the CLI (#316);
+     *  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 lab. */
 export type SharedWorldRunInput = Omit<RunConcurrentSharedWorldLabOptions, "config" | "dryRun" | "lab">;
-export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING"
-/** A local-agent brain's CLI is not on PATH. */
+export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING"
+/** A local-agent brain's CLI is not on `PATH`. */
  | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_MISSING"
 /** A local-agent brain's CLI is signed out, or could not report its sign-in status. */
  | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_AGENT_SIGNIN_REQUIRED"
 /** A dollar cap that cannot be priced: an unpriced model, or a ChatGPT-account Codex brain. */
  | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_UNPRICED_CAP" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT" | "HUMANISH_RUN_ID_IN_USE"
 /** A declared adopter-hosted comms catch (#328) did not answer as a humanish catch — fail closed
- *  BEFORE any actor spend, since the funnel would silently collect nothing. */
- | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE";
+ *  before any actor spend, since the funnel would silently collect nothing. */
+ | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE"
+/** comms.email.external.authTokenEnv names a token shorter than MIN_CATCH_TOKEN_LENGTH or not
+ *  well-formed Unicode (src/comms/external-evidence.ts). Refused before the catch is probed. */
+ | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_TOKEN_INVALID";
 /** The two plane classes of the concurrent shared-world route (#164 phase 2). */
 export type ConcurrentSharedWorldPlaneClass = "provisioned-getHost" | "external-public";
 export declare const EXTERNAL_PUBLIC_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", "external-public-plane", "operator-attested-target-not-harness-controlled", "no-synthetic-attestation", "no-authoritative-shared-state-proof", "concurrency-by-temporal-co-occupancy-only"];
-/** One persona's OUTCOME against the contended world (the "M of N" headline). */
+/** One persona's outcome against the contended world (the "M of N" headline). */
 export interface ConcurrentSharedWorldParticipantResult {
     id: string;
     index: number;
@@ -96,7 +109,7 @@ export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult
     actor: string;
     topology: "shared-world";
     topologyMode: "concurrent";
-    /** The DECLARED number of persona seats. */
+    /** The declared number of personas. */
     roleCount: number;
     /** Effective in-flight bound (execution.concurrency). */
     concurrency: number;
@@ -104,17 +117,17 @@ export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult
     runId: string;
     /** The harness-minted getHost URL the actors drove (tokenless; live only). */
     host?: string;
-    /** The ONE subject sandbox lifecycle proof. */
+    /** The one subject sandbox lifecycle proof. */
     subjectSandbox?: {
         sandboxId: string;
         killed: boolean;
     };
     /** Whether ≥2 actor windows overlapped in time (proven concurrency; live only). */
     overlapProven?: boolean;
-    /** Max lanes observed live at the same instant (live only) — the honest simultaneity number; a
-     *  6-lane run capped at 3 reports 3 here, never 6 (#350). */
+    /** Max participants observed live at the same instant (live only) — the honest simultaneity number; a
+     *  6-participant run capped at 3 reports 3 here, never 6 (#350). */
     maxSimultaneousLanes?: number;
-    /** Subject provenance (invariant 5): the ONE shared plane. */
+    /** Subject provenance (invariant 5): the one shared plane. */
     subject?: RunSubjectProvenance;
     roles: ConcurrentSharedWorldParticipantResult[];
     observer?: ObserverResult;
@@ -145,11 +158,12 @@ type StartedRun = Extract<Awaited<ReturnType<RunScope["startRun"]>>, {
 export interface PlaneContext {
     plan: SharedWorldPlan;
     input: SharedWorldRunInput;
-    /** Read by the computer-use lane runner, whose hooks and desktop setup take the whole config.
-     *  Seats, their count and their host and entry come from the plan's participants. */
+    /** Read for the subject's serve URL, which each seat's subject names. Seats, their count and
+     *  their host and entry come from the plan's participants. */
     config: LabConfig;
     descriptor: CuaActorDescriptor;
-    hooks: SharedWorldLabHooks;
+    /** The run's test seams; empty outside tests. */
+    deps: LabDeps;
     env: Record<string, string | undefined>;
     concurrency: number;
     runBudget: CuaRunBudget | undefined;
@@ -157,6 +171,8 @@ export interface PlaneContext {
     openaiApiKey: string;
     e2bApiKey: string;
     scrubKnownValues: (text: string) => string;
+    /** The values scrubKnownValues removes. Real email receiving adds its secrets before seats start. */
+    knownSecretValues: readonly string[];
     cwd: string;
     run: StartedRun;
     runId: string;
@@ -176,7 +192,7 @@ export interface PlaneContext {
 }
 /**
  * What the seats feed while they run. A plane sets the attached Observer and starts the trace
- * flush; the runtime stream hooks append stream URLs; the orchestrator reads all three at finish.
+ * flush; each seat's onStream appends stream URLs; the orchestrator reads all three at finish.
  */
 export interface LiveParticipants {
     observer?: ObserverResult & {
@@ -195,14 +211,12 @@ export interface ExternalCommsWiring {
 export interface ConcurrentBundleArgs {
     /** The run's judgment (judgeSharedWorldRun over the other fields). */
     judgment: SharedWorldJudgment;
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    run: BundleRun;
     plan: SharedWorldPlan;
     descriptor: CuaActorDescriptor;
-    createdAt: string;
     dryRun: boolean;
     inProgress?: boolean;
-    runId: string;
     source: RunBundle["source"];
     actorSpecs: DesktopParticipantRun[];
     actorResults: ActorRunResult[];
@@ -213,15 +227,15 @@ export interface ConcurrentBundleArgs {
     hostDigest?: string;
     /** Run-level digest-only comms-thread evidence path (humanish.comms-thread.v1), when a comms lab
      *  captured mail into the subject sandbox's catch. Registered on the first persona stream (it is a
-     *  property of the ONE shared app, not of any single persona). */
+     *  property of the one shared app, and belongs to no single persona). */
     commsArtifactPath?: string;
     /** #164 phase 2: the plane-class discriminator (default provisioned-getHost, byte-stable). */
     planeClass?: ConcurrentSharedWorldPlaneClass;
-    /** external-public only: sha256-16 of the OBSERVED origin the seats converged on (the convergence
+    /** external-public only: sha256-16 of the observed origin the seats converged on (the convergence
      *  proof — what the seats actually reached, tolerant of a declared->observed redirect). */
     publicOriginDigest?: string;
     /** external-public only: sha256-16 of the operator-DECLARED plane origin (evidence/reference only;
-     *  NOT asserted equal to the observed origin — a cross-origin redirect is normal and expected). */
+     *  never asserted equal to the observed origin, since a cross-origin redirect is normal). */
     declaredOriginDigest?: string;
     /** external-public only: sha256-16 of the shared /lobby/CODE path all seats converged on. */
     lobbyConvergenceDigest?: string;
@@ -236,6 +250,8 @@ export interface PlaneResults {
     subjectCommit: string | undefined;
     subjectSandboxId: string | undefined;
     subjectKilled: boolean;
+    /** The subject sandbox's scrubbed release warning when its release is unconfirmed. */
+    subjectReleaseWarning: string | undefined;
     subjectDesktop: SubjectDesktopUsage | undefined;
     getHostUrl: string | undefined;
     publicOriginDigest: string | undefined;
@@ -262,93 +278,4 @@ export interface FinishFacts {
     stateSnapshots: SharedWorldStateSnapshot[];
     declaredOriginDigest: string | undefined;
 }
-/**
- * Library-level hooks mirroring CuaActorLabHooks — the DI seams that let CI drive the FULL
- * orchestration with fakes at $0/zero-network. The fake desktop module records create/kill BY id
- * and exposes NO `list` method (the by-id teardown rail is then provable by construction).
- */
-export interface SharedWorldLabHooks extends BrowserLabAdapterHooks {
-    /** Lazy-load the E2B desktop module (tests inject a fake; default loadE2BDesktopModule). */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    /**
-     * Runs after a sandbox is created and before anything is provisioned on it. The provisioned
-     * plane calls it for the subject sandbox with no lane, then for each seat's desktop with its lane;
-     * the external-public plane calls it for the seats only.
-     */
-    prepareDesktop?: (desktop: E2BDesktopSandbox, lane?: {
-        laneId: string;
-        laneIndex: number;
-        laneCount: number;
-    }) => Promise<void>;
-    /**
-     * Awaited after a seat's live desktop stream starts. The URL carries an auth key and must never
-     * be persisted. A rejection becomes a run warning, as on the computer-use route.
-     */
-    onRuntimeStreamReady?: (stream: {
-        laneId: string;
-        sandboxId: string;
-        simId: string;
-        streamId: string;
-        url: string;
-    }) => Promise<void> | void;
-    /** Awaited after a seat's sandbox is gone, for seats whose stream started. Rejections are swallowed. */
-    onRuntimeStreamEnded?: (stream: {
-        laneId: string;
-        simId: string;
-        streamId: string;
-    }) => Promise<void> | void;
-    /** The per-seat computer-use session runner (default: the resolved actor descriptor's). */
-    runSession?: (options: CuaActorSessionOptions) => Promise<CuaLoopResult>;
-    /** The operator environment (keys + subject env values). Defaults to process.env. */
-    env?: Record<string, string | undefined>;
-    renderObserverFn?: typeof renderObserver;
-    /** Injected clock/sleep for the detached-step polling (tests only). */
-    detachedTimers?: DetachedTimers;
-    /**
-     * Subject-provisioning phase sink (mirrors CuaActorLabHooks.onPhase): one call per
-     * started/completed boundary during the ONE shared-plane provision (clone route: clone, install,
-     * build, serve start, ready, subject.state seed-step groups; local-tree route: upload, extract,
-     * install, build, serve start, ready, seed-step groups - no clone phase). Defaults to one stderr
-     * line per event. Override in tests to capture instead of writing to real stderr.
-     */
-    onPhase?: (event: SubjectPhaseEvent) => void;
-    /**
-     * CONCURRENT route only (#164 phase 2): the harness clock used to MEASURE each actor's laneWindow
-     * [start,end] (default Date.now). The deterministic heart test does NOT override this — overlap is
-     * produced by a rendezvous latch in the fake runSession + measured by the REAL clock (FIX-1), so
-     * the windows are real, not injected. (A test may override only for non-overlap assertions.)
-     */
-    now?: () => number;
-    /** CONCURRENT route only: the background stateSeries prober cadence (ms). Default 1000. */
-    proberCadenceMs?: number;
-    /**
-     * EXTERNAL-PUBLIC concurrent route only (#164 phase 2): the host-first handoff barrier deadline
-     * (ms). The host seat must surface a shared-session (/lobby/CODE) URL within this budget or the run
-     * fails closed with HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT and no follower opens.
-     * Default 120000 (also capped by execution.timeoutMs). Tests inject a short value to exercise the
-     * fail-closed path deterministically.
-     */
-    handoffDeadlineMs?: number;
-    /**
-     * EXTERNAL-PUBLIC concurrent route only: the vision reader that extracts a /lobby/CODE off a seat's
-     * screenshot frame (the CDP-independent handoff relay + per-seat convergence observation). Defaults to
-     * the real single-frame OpenAI read (readLobbyCodeFromFrame). Tests inject a fake so the barrier's
-     * handoff + convergence proof can be exercised deterministically without a live vision call.
-     */
-    readLobbyCodeFromFrame?: (frame: Buffer, apiKey: string) => Promise<string | undefined>;
-    /**
-     * Local-tree packing DI seam (tests only, no npm dependency needed to exercise the route):
-     * defaults to createLocalTreeArchive(root, opts) plus a host-side read of the produced archive
-     * file into an ArrayBuffer (the SAME default routes/computer-use/route.ts uses). Called ONCE per run, before
-     * the ONE shared-plane sandbox is created, on the live local-tree route.
-     */
-    packLocalTree?: (args: {
-        root: string;
-        extraExclude?: string[];
-        maxArchiveBytes?: number;
-    }) => Promise<{
-        archive: LocalTreeArchive;
-        buffer: ArrayBuffer;
-    }>;
-}
 export {};

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

@@ -5,7 +5,7 @@ export const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA = {
     mode: "concurrent-shared-world-lab",
     tool: "humanish",
 };
-// The verify-enforced CONCURRENT attribution ceiling (FIX-5). Mirrored in
+// The verify-enforced concurrent attribution ceiling. Mirrored in
 // verify/shared-world-concurrent.ts CONCURRENT_REQUIRED_LIMITS.
 export const CONCURRENT_ATTRIBUTION_LIMITS = [
     "concurrent",
@@ -16,7 +16,7 @@ export const CONCURRENT_ATTRIBUTION_LIMITS = [
     "state-change-not-isolated-to-actors",
 ];
 // EXTERNAL-PUBLIC plane class: the honest-downgrade attribution ceiling. The concurrent family
-// (an honest ceiling) PLUS the mandatory external-public disclosures — mirrored in the required
+// (an honest ceiling) plus the mandatory external-public disclosures, mirrored in the required
 // set in verify/shared-world-concurrent.ts (CONCURRENT_ATTRIBUTION_LIMITS +
 // EXTERNAL_PUBLIC_EXTRA_LIMITS). Verify fails closed on a missing one.
 export const EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS = [

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

@@ -1,27 +1,27 @@
 import type { ActorTrace } from "../../actors/contract.js";
 import { type RunBundle, type RunScorerProvenance } from "../../run/bundle.js";
 import { type ScorerOutcome } from "../../lab/adapter-extension.js";
-import type { TerminalLedgers, TerminalProductLabHooks } from "./types.js";
+import type { TerminalLedgers, TerminalScorer } from "./types.js";
 /**
  * Run the layer-6 product-adapter extension seam (issue #154 acceptance #8) over the assembled
- * evidence and attach its results to the bundle IN PLACE — without core knowing any product noun.
+ * evidence and attach its results to the bundle in place, without core knowing any product noun.
  * The review is not touched here: the returned failures are folded into it by the caller.
  *
  *  - `score`: when present, the returned namespaced `RunAdapterScore` lands on `bundle.adapterScore`.
- *    For a LIBRARY caller (no `scorerProvenance`), the adapter score is additive and never a
- *    failure. For a CONFIG-DECLARED scorer (#316; `scorerProvenance` present), a status:"fail" is a
- *    failure (the keystone lane is the product's own definition of pass/fail), and so is a scorer
- *    that THROWS or returns a malformed value, so a crashed declared gate is never a silent green.
+ *    For a library caller (no `scorerProvenance`), the adapter score is additive and never a
+ *    failure. For a config-declared scorer (#316; `scorerProvenance` present), a status:"fail" is a
+ *    failure (the keystone route is the product's own definition of pass/fail), and so is a scorer
+ *    that throws or returns a malformed value, so a crashed declared gate is never a silent green.
  *  - `deriveFeedback`: when present, the returned candidates are appended to
  *    `bundle.feedbackCandidates`; each carries its own namespaced `adapter` product-noun block.
  *
  * Defense in depth: the adapter's namespaced payloads are re-serialized through the run's scrub +
- * redact, and any candidate / score that does not satisfy core's exported shape is DROPPED with a
+ * redact, and any candidate / score that does not satisfy core's exported shape is dropped with a
  * warning (a malformed adapter output never poisons a verifiable bundle). The bundle verifier
  * re-checks the surviving shapes downstream, so the seam stays fail-closed end to end.
  */
 export declare function applyAdapterExtensionSeam(args: {
-    hooks: TerminalProductLabHooks;
+    scorer: TerminalScorer | undefined;
     bundle: RunBundle;
     trace: ActorTrace;
     ledgers: TerminalLedgers;

package/dist/routes/terminal/adapter.js

@@ -1,28 +1,27 @@
-import path from "node:path";
 import {} from "../../run/bundle.js";
-import { isFeedbackIdempotencyKey } from "../../run/feedback-shape.js";
-import { adapterScoreFailureMessage, declaredScorerThrew, DECLARED_SCORER_MALFORMED, frozenBundleView, } from "../../lab/adapter-extension.js";
+import { isRunAdapterScore } from "../../run/bundle-shape.js";
+import { adapterScoreFailureMessage, declaredScorerThrew, DECLARED_SCORER_MALFORMED, frozenBundleView, isAdapterFeedbackCandidate, } from "../../lab/adapter-extension.js";
 /**
  * Run the layer-6 product-adapter extension seam (issue #154 acceptance #8) over the assembled
- * evidence and attach its results to the bundle IN PLACE — without core knowing any product noun.
+ * evidence and attach its results to the bundle in place, without core knowing any product noun.
  * The review is not touched here: the returned failures are folded into it by the caller.
  *
  *  - `score`: when present, the returned namespaced `RunAdapterScore` lands on `bundle.adapterScore`.
- *    For a LIBRARY caller (no `scorerProvenance`), the adapter score is additive and never a
- *    failure. For a CONFIG-DECLARED scorer (#316; `scorerProvenance` present), a status:"fail" is a
- *    failure (the keystone lane is the product's own definition of pass/fail), and so is a scorer
- *    that THROWS or returns a malformed value, so a crashed declared gate is never a silent green.
+ *    For a library caller (no `scorerProvenance`), the adapter score is additive and never a
+ *    failure. For a config-declared scorer (#316; `scorerProvenance` present), a status:"fail" is a
+ *    failure (the keystone route is the product's own definition of pass/fail), and so is a scorer
+ *    that throws or returns a malformed value, so a crashed declared gate is never a silent green.
  *  - `deriveFeedback`: when present, the returned candidates are appended to
  *    `bundle.feedbackCandidates`; each carries its own namespaced `adapter` product-noun block.
  *
  * Defense in depth: the adapter's namespaced payloads are re-serialized through the run's scrub +
- * redact, and any candidate / score that does not satisfy core's exported shape is DROPPED with a
+ * redact, and any candidate / score that does not satisfy core's exported shape is dropped with a
  * warning (a malformed adapter output never poisons a verifiable bundle). The bundle verifier
  * re-checks the surviving shapes downstream, so the seam stays fail-closed end to end.
  */
 export async function applyAdapterExtensionSeam(args) {
-    const { hooks, bundle, trace, ledgers, transcript, product, labId, runId, sanitize, warnings, scorerProvenance, } = args;
-    if (!hooks.score && !hooks.deriveFeedback)
+    const { scorer, bundle, trace, ledgers, transcript, product, labId, runId, sanitize, warnings, scorerProvenance, } = args;
+    if (!scorer?.score && !scorer?.deriveFeedback)
         return { failures: [] };
     const declared = scorerProvenance !== undefined;
     // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
@@ -31,7 +30,7 @@ export async function applyAdapterExtensionSeam(args) {
         bundle.scorerProvenance = scorerProvenance;
     // The scorer sees a READ-ONLY view of the bundle so it cannot mutate noSpend/cost/review in place to
     // launder a verdict (a tamper attempt throws and is caught as a hook failure below). The seam stamps
-    // the REAL bundle. The transcript is the SAME normalized, source-scrubbed text the run persists as
+    // the real bundle. The transcript is the same normalized, source-scrubbed text the run persists as
     // terminal-transcript.txt — no new exposure beyond what disk already holds (#341).
     const ctx = {
         bundle: frozenBundleView(bundle),
@@ -43,21 +42,22 @@ export async function applyAdapterExtensionSeam(args) {
         runId,
     };
     // Best-effort re-scrub of the adapter payload: round-trip the whole JSON through the run's denylist
-    // sanitizer. This is NOT containment — it catches recognizable secret shapes and known local paths,
-    // but not encoded/split/custom secrets, DB passwords, PII, or abs paths outside the denylist. A
+    // sanitizer. It is a scrub with no containment: it catches recognizable secret shapes and known
+    // local paths, and misses encoded/split/custom secrets, DB passwords, PII, or abs paths outside
+    // the denylist. A
     // payload from config-declared code is acceptable only because the trust boundary (the party who
     // declares the scorer runs the lab) already permits direct exfiltration; the re-scrub is
     // defense-in-depth, not a wall.
     const scrubValue = (value) => JSON.parse(sanitize(JSON.stringify(value)));
-    // Set for a DECLARED scorer that fails to render a PASS verdict (status:"fail", malformed, or throw).
-    // The caller folds it into the review and fails the run RESULT on it — a declared gate that cannot
+    // Set for a declared scorer that fails to render a pass verdict (status:"fail", malformed, or throw).
+    // The caller folds it into the review and fails the run result on it: a declared gate that cannot
     // pass is a fail, never a silent green. Empty for a library caller and for a passing scorer.
     const failures = [];
-    if (hooks.score) {
+    if (scorer?.score) {
         try {
-            const score = await hooks.score(ctx);
+            const score = await scorer.score(ctx);
             const cleaned = scrubValue(score);
-            if (isAdapterScoreShape(cleaned)) {
+            if (isRunAdapterScore(cleaned)) {
                 bundle.adapterScore = cleaned;
                 // A CONFIG-DECLARED terminal scorer owns the product verdict: a status:"fail" fails the
                 // review and the run result. A library caller keeps the additive no-fail behavior.
@@ -66,136 +66,39 @@ export async function applyAdapterExtensionSeam(args) {
                     failures.push(message);
             }
             else {
-                warnings.push("terminalHooks.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.");
-                // A declared gate that returned a MALFORMED value never rendered a verdict — fail closed.
+                warnings.push("scorer.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.");
+                // A declared gate that returned a malformed value never rendered a verdict, so it fails closed.
                 if (declared)
                     failures.push(DECLARED_SCORER_MALFORMED);
             }
         }
         catch (error) {
             const detail = sanitize(error instanceof Error ? error.message : String(error));
-            warnings.push(`terminalHooks.score threw (${detail}); dropped so the bundle stays verifiable.`);
-            // A crashed DECLARED gate must be visible, never a silent pass: it fails the review and the
+            warnings.push(`scorer.score threw (${detail}); dropped so the bundle stays verifiable.`);
+            // A crashed declared gate must be visible, never a silent pass: it fails the review and the
             // run result.
             if (declared)
                 failures.push(declaredScorerThrew(detail));
         }
     }
-    if (hooks.deriveFeedback) {
+    if (scorer?.deriveFeedback) {
         try {
-            const candidates = await hooks.deriveFeedback(ctx);
+            const candidates = await scorer.deriveFeedback(ctx);
             const accepted = [];
             for (const candidate of Array.isArray(candidates) ? candidates : []) {
                 const cleaned = scrubValue(candidate);
-                if (isAdapterFeedbackCandidateShape(cleaned))
+                if (isAdapterFeedbackCandidate(cleaned))
                     accepted.push(cleaned);
                 else
-                    warnings.push("terminalHooks.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.");
+                    warnings.push("scorer.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.");
             }
             if (accepted.length > 0) {
                 bundle.feedbackCandidates = [...bundle.feedbackCandidates, ...accepted];
             }
         }
         catch (error) {
-            warnings.push(`terminalHooks.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+            warnings.push(`scorer.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
         }
     }
     return { failures };
 }
-/** Structural guard for an adapter-returned RunAdapterScore (mirrors run/bundle-shape.ts isRunAdapterScore, kept
- *  local so the lane fails closed at the seam BEFORE the bundle verifier re-checks it). */
-function isAdapterScoreShape(value) {
-    return (typeof value === "object" &&
-        value !== null &&
-        !Array.isArray(value) &&
-        value.schema === "humanish.adapter-score.v1" &&
-        typeof value.namespace === "string" &&
-        value.namespace.trim().length > 0 &&
-        ["pass", "partial", "fail"].includes(value.status) &&
-        typeof value.score === "number" &&
-        Number.isFinite(value.score) &&
-        typeof value.summary === "string");
-}
-/** Structural guard for an adapter-returned feedback candidate. This mirrors run/feedback-shape.ts's full
- * isRunFeedbackCandidate predicate, including its local evidence-path contract, so a malformed
- * candidate is dropped at the extension seam instead of poisoning the persisted bundle. */
-function isAdapterFeedbackCandidateShape(value) {
-    return (isAdapterRecord(value) &&
-        value.schema === "humanish.feedback-candidate.v1" &&
-        typeof value.id === "string" &&
-        typeof value.run_id === "string" &&
-        (typeof value.stream_id === "string" || value.stream_id === undefined) &&
-        typeof value.adapter_id === "string" &&
-        typeof value.scenario_id === "string" &&
-        typeof value.persona_id === "string" &&
-        isAdapterFeedbackActor(value.actor) &&
-        isAdapterFeedbackSubstrate(value.substrate) &&
-        isAdapterFeedbackFailureOwner(value.failure_owner) &&
-        typeof value.summary === "string" &&
-        value.summary.trim().length > 0 &&
-        typeof value.expected === "string" &&
-        typeof value.actual === "string" &&
-        Array.isArray(value.evidence) &&
-        value.evidence.every(isAdapterFeedbackEvidence) &&
-        isAdapterRecord(value.redaction) &&
-        value.redaction.status === "passed" &&
-        typeof value.redaction.notes === "string" &&
-        isFeedbackIdempotencyKey(value.idempotency_key) &&
-        isAdapterFeedbackNextState(value.proposed_next_state) &&
-        Array.isArray(value.acceptance_proof) &&
-        value.acceptance_proof.every((item) => typeof item === "string") &&
-        (value.adapter === undefined ||
-            (isAdapterRecord(value.adapter) &&
-                typeof value.adapter.namespace === "string" &&
-                value.adapter.namespace.trim().length > 0 &&
-                isAdapterRecord(value.adapter.data))));
-}
-function isAdapterFeedbackEvidence(value) {
-    return (isAdapterRecord(value) &&
-        typeof value.path === "string" &&
-        value.path.length > 0 &&
-        !path.isAbsolute(value.path) &&
-        !value.path.includes("://") &&
-        !value.path.includes("..") &&
-        (value.kind === "review" ||
-            value.kind === "state" ||
-            value.kind === "log" ||
-            value.kind === "trace" ||
-            value.kind === "screenshot" ||
-            value.kind === "filesystem") &&
-        typeof value.note === "string");
-}
-function isAdapterFeedbackActor(value) {
-    return (value === "codex-tui" ||
-        value === "codex-exec" ||
-        value === "codex-app-server" ||
-        value === "computer-use" ||
-        value === "synthetic-dry-run" ||
-        value === "unknown");
-}
-function isAdapterFeedbackSubstrate(value) {
-    return (value === "e2b-desktop" ||
-        value === "local-desktop" ||
-        value === "e2b-terminal" ||
-        value === "local-filesystem" ||
-        value === "codex-app-server" ||
-        value === "unknown");
-}
-function isAdapterFeedbackFailureOwner(value) {
-    return (value === "harness" ||
-        value === "target-app" ||
-        value === "actor" ||
-        value === "environment" ||
-        value === "unknown");
-}
-function isAdapterFeedbackNextState(value) {
-    return (value === "watch" ||
-        value === "adapter-hardening" ||
-        value === "target-app-setup" ||
-        value === "actor-auth" ||
-        value === "setup-quality-review" ||
-        value === "study-quality-review");
-}
-function isAdapterRecord(value) {
-    return typeof value === "object" && value !== null && !Array.isArray(value);
-}

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

@@ -1,21 +1,19 @@
 import type { ActorPersonaRef, ActorTrace } from "../../actors/contract.js";
-import { type RunLabProvenance } from "../../run/status.js";
 import type { LabScenarioCaps, LabRuntimeAuth } from "../../lab/types.js";
-import { type RunBundle, type RunCostSummary } from "../../run/bundle.js";
+import { type RunBundle, type RunCostSummary, type BundleRun } from "../../run/bundle.js";
 import type { Verdict } from "../../run/judge.js";
 import type { TerminalLedgers } from "./types.js";
 /**
  * Project the terminal-product lab run into a humanish.run-bundle.v1 (no schema change — a new
  * producer only). DRY-RUN: a contract bundle. The terminal stream is a contract placeholder
- * (stdin disabled, no captured tail — honest: nothing ran), the subject is declared UNPINNED, and
+ * (stdin disabled, no captured tail, because nothing ran), the subject is declared unpinned, and
  * the caps/policies/runtime-auth declarations are recorded without pretending that live ledgers
  * exist. The shipped live builder fills the same evidence contract. Exported for tests.
  */
 export declare function buildTerminalProductBundle(args: {
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    run: BundleRun;
     actorId: string;
-    createdAt: string;
     dryRun: boolean;
     labId: string;
     labTitle?: string;
@@ -32,23 +30,21 @@ export declare function buildTerminalProductBundle(args: {
         allowPaymentCredentials: boolean;
         allowGitHubMutation: boolean;
     };
-    runId: string;
     source: RunBundle["source"];
     /** The run's judgment verdict (judgeTerminal): a contract for a dry run. */
     verdict: Verdict;
 }): RunBundle;
 /**
- * Build the LIVE terminal-product run bundle (mode "live") from the captured session: the actor
+ * Build the live terminal-product run bundle (mode "live") from the captured session: the actor
  * trace seam (stream.actor = trace), the substrate-lifecycle events, the terminal stream with the
  * redacted transcript tail, and references to the written evidence artifacts (terminal event
  * stream, transcript, ledgers, actor trace). verifyRun's terminal-product check (gated on
  * mode==="live") enforces the ledgers + proven cleanup + interventions-present over this bundle.
  */
 export declare function buildLiveTerminalProductBundle(args: {
-    /** Lab provenance for the bundle\'s own `lab` field (#455). */
-    lab?: RunLabProvenance;
+    /** The run this bundle belongs to; the bundle head reads its id, mode, start and lab. */
+    run: BundleRun;
     actorId: string;
-    createdAt: string;
     labId: string;
     labTitle?: string;
     mission: string;
@@ -64,7 +60,6 @@ export declare function buildLiveTerminalProductBundle(args: {
         allowPaymentCredentials: boolean;
         allowGitHubMutation: boolean;
     };
-    runId: string;
     source: RunBundle["source"];
     trace: ActorTrace;
     ledgers: TerminalLedgers;