humanish 0.106.1 → 0.107.0

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

@@ -1,48 +1,31 @@
 import type { ActorCompletionReason, ActorStatus } from "../../actors/contract.js";
-import type { ScriptedBrowserSessionOptions, ScriptedBrowserSessionResult } from "../../actors/scripted-browser/actor.js";
-import type { ScriptedBrowserLaunchArgs, ScriptedBrowserLike } from "../../actors/scripted-browser/types.js";
-import type { AutomaticAnalysisHooks, AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
+import type { LabEvent } from "../../lab/run-lab-events.js";
+import type { AutomaticAnalysisResult } from "../../analysis/automatic-completion.js";
 import type { LabConfig } from "../../lab/types.js";
-import { renderObserver, type ObserverResult } from "../../observer/render.js";
+import type { ObserverResult } from "../../observer/render.js";
 import type { RunSubjectProvenance } from "../../run/bundle.js";
-import type { RunLabProvenance } from "../../run/status.js";
-import type { DetachedTimers } from "../../substrates/detached.js";
-import type { E2BDesktopModule, E2BDesktopSandbox } from "../../substrates/e2b/sdk.js";
+import type { LabDeps } from "../../lab/lab-deps.js";
+import type { RunLabHomes } from "../../lab/run-lab-homes.js";
 export declare const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";
-/**
- * Library-level hooks: DI seams so CI drives the full path (real engine, real projection)
- * with a fake browser at zero spend, plus the production browser resolution override.
- */
-export interface ScriptedBrowserLabHooks {
-    runSession?: (options: ScriptedBrowserSessionOptions) => Promise<ScriptedBrowserSessionResult>;
-    /** Injected browser factory — forwarded to every session; skips browser-binary resolution. */
-    launchBrowser?: (args: ScriptedBrowserLaunchArgs) => Promise<ScriptedBrowserLike>;
-    /** Test/library env seam; CLI passes process.env. Values are scrubbed, names only persist. */
-    env?: Record<string, string | undefined>;
-    /** E2B DI seam for clone × e2b-desktop × scripted-browser. */
-    loadDesktopModule?: () => Promise<E2BDesktopModule>;
-    /** Optional adopter hook after subject sandbox creation, before clone provisioning. */
-    prepareDesktop?: (desktop: E2BDesktopSandbox) => Promise<void>;
-    /** Detached-step timers for deterministic tests around clone/seed/start provisioning. */
-    detachedTimers?: DetachedTimers;
-    /** Override the resolved browser binary (tests; operators use HUMANISH_BROWSER_COMMAND). */
-    browserCommand?: string;
-    renderObserverFn?: typeof renderObserver;
-    now?: () => number;
-}
 /** What a scripted run takes besides its plan. The plan carries the config, dry run and lab. */
 export type ScriptedRunInput = Omit<RunScriptedBrowserLabOptions, "config" | "dryRun" | "lab">;
 export interface RunScriptedBrowserLabOptions {
-    automaticAnalysis?: AutomaticAnalysisHooks;
-    /** Which manifest produced this run (#455); threaded into the status record + bundle. */
-    lab?: RunLabProvenance;
+    /** Cancels post-run analysis only. */
+    analysisSignal?: AbortSignal;
+    /** Reports the analysis window to onEvent; built by normalizeRunLabOptions. */
+    emit?: (event: LabEvent) => void;
     cwd: string;
     config: LabConfig;
     /** Resolved upstream (scenario.mode + CLI override); defaults safe (dry-run). */
     dryRun: boolean;
     open?: boolean;
     runId?: string;
-    hooks?: ScriptedBrowserLabHooks;
+    /** Keys and subject env for the run. Defaults to process.env. Values are scrubbed; names persist. */
+    env?: Readonly<Record<string, string | undefined>>;
+    /** Runs after a clone subject's sandbox exists and before provisioning. */
+    prepareDesktop?: NonNullable<RunLabHomes["prepareDesktop"]>;
+    /** Test seams: the browser, the session, the E2B module, timers, the renderer and the clock. */
+    deps?: LabDeps;
 }
 interface ScriptedBrowserLabSession {
     surface: string;
@@ -53,9 +36,9 @@ interface ScriptedBrowserLabSession {
 }
 export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
     schema: typeof SCRIPTED_BROWSER_LAB_SCHEMA;
-    /** True when the bundle verified AND (dry-run, or every session reached a terminal verdict
-     * without a harness error). The subject failing the script is successful EVIDENCE, not a lab
-     * failure. */
+    /** True when the bundle verified and (dry-run, or every session reached a terminal verdict
+     * without a harness error). The subject failing the script is successful evidence, and the lab
+     * does not fail for it. */
     ok: boolean;
     cwd: string;
     labId: string;
@@ -81,7 +64,7 @@ export interface ScriptedBrowserLabResult extends AutomaticAnalysisResult {
     observer?: ObserverResult;
     warnings: string[];
     error?: {
-        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_CONFLICT" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_FAILED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_LAB_BROWSER_MISSING" | "HUMANISH_SCRIPTED_LAB_KEYS_MISSING" | "HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
+        code: "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_LAB_OPTION_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_FAILED" | "HUMANISH_SCRIPTED_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_SCRIPTED_LAB_SCENARIO_INVALID" | "HUMANISH_SCRIPTED_LAB_SUBJECT_UNSAFE" | "HUMANISH_SCRIPTED_LAB_BROWSER_MISSING" | "HUMANISH_SCRIPTED_LAB_KEYS_MISSING" | "HUMANISH_SCRIPTED_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_SCRIPTED_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_RUN_ID_IN_USE";
         message: string;
     };
 }

package/dist/routes/scripted/types.js

@@ -1,3 +1,2 @@
-// The scripted-browser lab's schema constant, library hooks, options and result types.
-import { renderObserver } from "../../observer/render.js";
+// The scripted-browser lab's schema constant, options and result types.
 export const SCRIPTED_BROWSER_LAB_SCHEMA = "humanish.scripted-lab-result.v1";

package/dist/routes/shared-world/{seat-records.js → bundle-records.js}

@@ -5,7 +5,7 @@ import { participantAssignment } from "../../lab/participant-assignment.js";
 import { participantEvent, participantRecord, participantStream, } from "../../run/participant-records.js";
 import { declaredScreenForRender } from "../../substrates/e2b/desktop-geometry.js";
 import { publicSafeRouteLabel } from "./provenance.js";
-import { participantTaxonomyLabel } from "./seats.js";
+import { participantTaxonomyLabel } from "./participant-specs.js";
 function participantView(ctx, spec, index) {
     const { args, external, inProgress } = ctx;
     const taxonomy = participantTaxonomyLabel(spec.planned.labels);
@@ -31,8 +31,8 @@ function participantView(ctx, spec, index) {
             ? "Actor desktop is running; the attached Observer hydrates the runtime stream URL without persisting it."
             : "Contract actor only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
     const traceScreenshotMode = session?.trace.redaction.screenshots;
-    // Include `declared` on the no-outcome fallback too (dry-run, skipped lane): otherwise an
-    // ABSENT declared means either "the preset rendered faithfully" or "there was no live
+    // Include `declared` on the no-outcome fallback too (dry-run, skipped participant): otherwise an
+    // absent `declared` means either "the preset rendered faithfully" or "there was no live
     // outcome", and a dry-run bundle keeps the self-confirming shape this field exists to kill.
     const fallbackDeclared = declaredScreenForRender(spec.planned.device.preset, spec.planned.device.name, spec.planned.device.resolution);
     const desktopGeometry = outcome?.desktopGeometry ?? {
@@ -80,8 +80,8 @@ function sharedWorldSimulation(ctx, spec, index, view) {
                 : inProgress
                     ? `Persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) is running against the shared plane.`
                     : `Contract persona ${spec.planned.id}${taxonomy} (${spec.persona.id}) for ${args.descriptor.id} against the shared plane at ${ctx.appUrl}.`,
-        startedAt: args.createdAt,
-        updatedAt: args.createdAt,
+        startedAt: args.run.createdAt,
+        updatedAt: args.run.createdAt,
     });
 }
 function sharedWorldStream(ctx, spec, index, view) {
@@ -95,7 +95,7 @@ function sharedWorldStream(ctx, spec, index, view) {
         label: `Concurrent persona ${spec.planned.id}${taxonomy} — ${args.plan.labId}`,
         status: view.status,
         transport: "snapshot",
-        updatedAt: args.createdAt,
+        updatedAt: args.run.createdAt,
         embed: lastScreenshot
             ? {
                 kind: "screenshot",
@@ -135,7 +135,7 @@ function sharedWorldStream(ctx, spec, index, view) {
                     },
                 ]
                 : []),
-            // Run-level comms evidence belongs to the ONE shared app, not a persona — register it once, on
+            // Run-level comms evidence belongs to the one shared app, and to no persona: register it once, on
             // the first stream, so the bundle's existence-verify + public-safety scan cover it without
             // double-counting across seats.
             ...(index === 0 && args.commsArtifactPath
@@ -151,7 +151,7 @@ function sharedWorldStream(ctx, spec, index, view) {
 }
 function sharedWorldEvents(ctx, spec, view) {
     const { args, inProgress, nextEventId } = ctx;
-    const createdAt = args.createdAt;
+    const createdAt = args.run.createdAt;
     const { outcome, session } = view;
     const events = [];
     const record = (event) => events.push(participantEvent(spec, event));

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

@@ -2,7 +2,7 @@ import { type RunBundle } from "../../run/bundle.js";
 import { type SharedWorldJudgment } from "../../run/judge.js";
 import { type ActorRunResult, type ConcurrentBundleArgs } from "./types.js";
 /** Max windows live at the same instant (sweep over start/end points). The honest simultaneity
- *  count: lane COUNT says how many seats existed; this says how many ever ran at once. */
+ *  count: the participant count says how many existed; this says how many ever ran at once. */
 export declare function maxSimultaneousWindows(windows: Array<{
     startedAt: number;
     endedAt: number;
@@ -15,6 +15,6 @@ export declare function maxSimultaneousWindows(windows: Array<{
  */
 export declare function judgeSharedWorldRun(args: Omit<ConcurrentBundleArgs, "judgment">): SharedWorldJudgment;
 export declare function actorRunPassed(result: ActorRunResult | undefined): boolean;
-/** Project the concurrent run into a humanish.run-bundle.v1 with the CONCURRENT shared-world block. */
+/** Project the concurrent run into a humanish.run-bundle.v1 with the concurrent shared-world block. */
 export declare function buildConcurrentSharedWorldBundle(args: ConcurrentBundleArgs): RunBundle;
 export declare function renderConcurrentReviewMarkdown(bundle: RunBundle): string;

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

@@ -12,10 +12,10 @@ import { judgeSharedWorld, participantPassed, sharedWorldShortfall, } from "../.
 import { combineCheckpointDigest } from "./checkpoints.js";
 import { hostOriginDigest } from "./provenance.js";
 import { participantEvent, participantIds } from "../../run/participant-records.js";
-import { sharedWorldParticipantRecords } from "./seat-records.js";
+import { sharedWorldParticipantRecords } from "./bundle-records.js";
 import { CONCURRENT_ATTRIBUTION_LIMITS, EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS, } from "./types.js";
 /** Max windows live at the same instant (sweep over start/end points). The honest simultaneity
- *  count: lane COUNT says how many seats existed; this says how many ever ran at once. */
+ *  count: the participant count says how many existed; this says how many ever ran at once. */
 export function maxSimultaneousWindows(windows) {
     const points = windows
         .filter((w) => w.endedAt > w.startedAt)
@@ -90,7 +90,7 @@ function formatSharedWorldActorOutcomes(outcomes, expectedCount) {
 }
 /** The run's first two events: its creation and the shared plane's provenance. */
 function planeEvents(args, external) {
-    const { plan, descriptor, createdAt, dryRun, actorSpecs } = args;
+    const { plan, descriptor, run: { createdAt }, dryRun, actorSpecs, } = args;
     const events = [];
     events.push({
         id: "event-000-created",
@@ -108,8 +108,8 @@ function planeEvents(args, external) {
             ? `packed working tree (archiveSha256 ${args.subject.archiveSha256}${args.subject.dirty === true ? ", dirty working tree" : args.subject.dirty === false ? ", clean working tree" : ""})`
             : "packed working tree (archive digest unresolved; provisioning failed before resolution)"
         : `clone of ${args.subject.repo}${args.subjectCommit ? `@${args.subjectCommit}` : ""}`;
-    // External-public plane provenance is HONESTLY different: an operator-declared, operator-OWNED
-    // public deployment humanish neither provisioned nor seeded — NO getHost, NO clone, NO synthetic
+    // External-public plane provenance differs: an operator-declared, operator-owned public
+    // deployment humanish neither provisioned nor seeded, with no getHost, no clone and no synthetic
     // attestation (claiming synthetic on a real site is a lie). The origin persists digest-only.
     // planSharedWorldLab refuses an external-public plane without a declared owner; the fallback
     // says so rather than naming one.
@@ -130,7 +130,7 @@ function planeEvents(args, external) {
 /** The sharedWorld block: seat windows, the state series, seat outcomes and the plane. */
 function sharedWorldEvidence(args, external, inProgress, planeCommit) {
     const { plan, dryRun, actorSpecs, actorResults } = args;
-    // Build the concurrent shared-world evidence block. routeHostDigest is sha256-16 of the ORIGIN each
+    // Build the concurrent shared-world evidence block. routeHostDigest is sha256-16 of the origin each
     // seat reached: on getHost the seat URL the actor drove (verify confirms == plane.hostDigest); on
     // external-public the seat's CDP-OBSERVED URL origin (verify confirms == plane.publicOriginDigest).
     const fallbackHostDigest = external
@@ -156,7 +156,7 @@ function sharedWorldEvidence(args, external, inProgress, planeCommit) {
             seedDigest: args.seedDigest,
         };
     });
-    // Option A (external-public): NO authoritative shared-state proof — OMIT stateSeries entirely (there
+    // Option A (external-public): no authoritative shared-state proof, so stateSeries is omitted (there
     // is no in-sandbox filesystem to digest; concurrency is proven by temporal co-occupancy + lobby
     // convergence). The provisioned-getHost plane keeps its authoritative in-sandbox checkpoint series.
     const stateSeries = external
@@ -182,13 +182,13 @@ function sharedWorldEvidence(args, external, inProgress, planeCommit) {
         };
     });
     // The plane block is plane-class-specific. getHost: harness-minted hostDigest + synthetic
-    // attestation. external-public: operator-declared publicOriginDigest, NO hostDigest, NO exposure
-    // (claiming synthetic on a real site would be a lie — verify asserts both ABSENT there).
+    // attestation. external-public: operator-declared publicOriginDigest, no hostDigest, no exposure
+    // (claiming synthetic on a real site would be false; verify asserts both are absent there).
     const plane = external
         ? {
             seedDigest: args.seedDigest,
             envNames: [],
-            // publicOriginDigest is the OBSERVED convergence origin; declaredOriginDigest records the
+            // publicOriginDigest is the observed convergence origin; declaredOriginDigest records the
             // operator-declared origin for reference (a redirect makes them differ — not a failure).
             ...(args.publicOriginDigest === undefined
                 ? {}
@@ -216,7 +216,7 @@ function sharedWorldEvidence(args, external, inProgress, planeCommit) {
             ? [...EXTERNAL_PUBLIC_ATTRIBUTION_LIMITS]
             : [...CONCURRENT_ATTRIBUTION_LIMITS],
         laneWindows: windows,
-        // Option A: external-public carries NO stateSeries.
+        // Option A: external-public carries no stateSeries.
         ...(stateSeries === undefined ? {} : { stateSeries }),
         outcomes,
         ...(args.lobbyConvergenceDigest === undefined
@@ -241,7 +241,7 @@ function finishedGaps(actorResults, shortfall) {
 }
 /** Records the concurrency event and returns the review. */
 function concurrencyReview(args, external, inProgress, evidence, events, nextEventId) {
-    const { plan, descriptor, createdAt, dryRun, actorSpecs, actorResults } = args;
+    const { plan, descriptor, run: { createdAt }, dryRun, actorSpecs, actorResults, } = args;
     const { sharedWorld, windows, stateSeries, outcomes } = evidence;
     const overlaps = args.judgment.world.overlap;
     const deltas = (stateSeries ?? []).filter((snapshot, i) => i > 0 && snapshot.digest !== (stateSeries ?? [])[i - 1].digest).length;
@@ -251,8 +251,8 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const convergenceLabel = external
         ? `; lobby convergence ${args.lobbyConvergenceDigest ? "PROVEN (all participants reached one /lobby/CODE)" : "not observed"}`
         : "";
-    // The count that matters is how many lanes were LIVE AT ONCE, not how many lanes exist — a
-    // 6-lane run capped at 3 must never read as 6-wide concurrency (#350, the field failure).
+    // The count that matters is how many participants were live at once, which can be fewer than exist:
+    // a 6-participant run capped at 3 must never read as 6-wide concurrency (#350, the field failure).
     const capForReport = plan.concurrency;
     const maxLive = maxSimultaneousWindows(windows);
     events.push({
@@ -262,7 +262,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
         type: "concurrent-shared-world.concurrency",
         message: `Concurrency: ${windows.length} participant(s)${dryRun ? " (dry-run contract; $0)" : `, up to ${maxLive} live at once (cap ${capForReport}), overlap ${overlaps ? "PROVEN" : "not observed"}`}; ${stateSeriesLabel}${convergenceLabel}. Attribution ceiling: ${sharedWorld.attributionLimits.join(", ")}. ${dryRun ? "This contract-only run proves no live concurrency, scale, or adoption." : "This run reports only its own observed overlap and state changes; it does not prove scale, repeatability, or adopter-harness replacement."}`,
     });
-    // The judge's verdict (judgeSharedWorld): every seat produced a terminal, engaged PASSED session.
+    // The judge's verdict (judgeSharedWorld): every seat produced a terminal, engaged, passed session.
     // Mission endpoint and completion reasons are reported separately below; `outcomes[].ok` is not
     // renamed into mission success (#364).
     const verdict = args.judgment.verdict;
@@ -270,7 +270,7 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     const review = {
         schema: REVIEW_SCHEMA,
         verdict,
-        // Plane-class-aware: the external-public plane has NO getHost/clone/seed and carries NO
+        // Plane-class-aware: the external-public plane has no getHost/clone/seed and carries no
         // authoritative state series, so its summary must not claim a getHost-exposed plane (dry-run) nor
         // report "state delta(s) under load" (live) — it reports lobby convergence instead.
         summary: dryRun
@@ -294,15 +294,15 @@ function concurrencyReview(args, external, inProgress, evidence, events, nextEve
     };
     return review;
 }
-/** Project the concurrent run into a humanish.run-bundle.v1 with the CONCURRENT shared-world block. */
+/** Project the concurrent run into a humanish.run-bundle.v1 with the concurrent shared-world block. */
 export function buildConcurrentSharedWorldBundle(args) {
-    const { plan, descriptor, createdAt, dryRun, actorSpecs, actorResults } = args;
+    const { plan, descriptor, run: { createdAt }, dryRun, actorSpecs, actorResults, } = args;
     const inProgress = args.inProgress === true;
     const external = (args.planeClass ?? "provisioned-getHost") === "external-public";
     const simulations = [];
     const streams = [];
     // Public-safe label only — neither the raw getHost URL (provisioned) nor the raw public origin
-    // (external-public) lands in the bundle. The plane identity is a DIGEST (plane.hostDigest on
+    // (external-public) lands in the bundle. The plane identity is a digest (plane.hostDigest on
     // getHost; plane.publicOriginDigest on external-public).
     const appUrl = external ? "[external-public-plane]" : "[provisioned-subject]";
     const planeCommit = external ? undefined : dryRun ? undefined : args.subjectCommit;
@@ -323,13 +323,9 @@ export function buildConcurrentSharedWorldBundle(args) {
     const ranLive = actorResults.some((result) => result.outcome.session !== undefined || result.outcome.sessionError !== undefined);
     const cost = concurrentCostSummary(args, inProgress);
     return {
-        ...bundleHead({
+        ...bundleHead(args.run, {
             ...receivingPublication(plan.residual, args.dryRun),
-            runId: args.runId,
-            mode: dryRun ? "dry-run" : "live",
             participants: actorSpecs.length,
-            createdAt,
-            ...(args.lab === undefined ? {} : { lab: args.lab }),
             source: args.source,
         }),
         persona: {
@@ -381,7 +377,7 @@ export function buildConcurrentSharedWorldBundle(args) {
     };
 }
 /**
- * Priced like per-lane worlds: each seat's model tokens and desktop, plus the provisioned plane's
+ * Priced like `per-lane-worlds`: each participant's model tokens and desktop, plus the provisioned plane's
  * desktop. Absent when nothing ran, so dry runs and in-progress snapshots stay byte-stable.
  */
 function concurrentCostSummary(args, inProgress) {
@@ -416,7 +412,7 @@ function concurrentCostSummary(args, inProgress) {
         ],
     });
 }
-/** The declared (dry-run) state digest: the probe RECIPE (command digests), no run. */
+/** The declared (dry-run) state digest: the probe recipe (command digests), no run. */
 function declaredStateDigest(state) {
     const probes = state?.checkpoint ?? [];
     return combineCheckpointDigest(probes.map((probe) => `${probe.name}=${commandDigestOf(probe.command)}`));

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

@@ -2,12 +2,12 @@ import type { Shell } from "../../substrates/shell.js";
 import { type DetachedTimers } from "../../substrates/detached.js";
 import { type LabSubjectState, type LabSubjectStateCheckpoint } from "../../lab/types.js";
 import { type SharedWorldCheckpoint } from "../../run/shared-world-evidence.js";
-/** Combine a snapshot's per-probe digests into ONE sha256-16 (digest-only; no raw value). */
+/** Combine a snapshot's per-probe digests into one sha256-16 (digest-only; no raw value). */
 export declare function combineCheckpointDigest(parts: string[]): string;
 /**
- * Run ONE checkpoint snapshot LIVE: each declared probe runs read-only via the detached
+ * Run one checkpoint snapshot live: each declared probe runs read-only via the detached
  * primitive; its stdout is literal-scrubbed (provisioned values + the probe's declared redact
- * literals, folded into `scrub`) then pattern-redacted, then digested. Only the COMBINED digest
+ * literals, folded into `scrub`) then pattern-redacted, then digested. Only the combined digest
  * persists — never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
  * stale-status reuse across snapshots.
  */
@@ -21,5 +21,5 @@ export declare function runCheckpointSnapshot(args: {
     requestTimeoutMs: number;
     timers: DetachedTimers;
 }): Promise<SharedWorldCheckpoint>;
-/** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity. */
+/** sha256-16 over the ordered seed-step command digests: the seeded-state recipe identity. */
 export declare function seedRecipeDigest(state: LabSubjectState | undefined): string;

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

@@ -6,14 +6,14 @@ import { redactText } from "../../evidence/redaction.js";
 import {} from "../../run/shared-world-evidence.js";
 // Per-checkpoint probe budget (read-only aggregate probes are fast).
 const CHECKPOINT_TIMEOUT_MS = 60_000;
-/** Combine a snapshot's per-probe digests into ONE sha256-16 (digest-only; no raw value). */
+/** Combine a snapshot's per-probe digests into one sha256-16 (digest-only; no raw value). */
 export function combineCheckpointDigest(parts) {
     return commandDigestOf(parts.join("\n"));
 }
 /**
- * Run ONE checkpoint snapshot LIVE: each declared probe runs read-only via the detached
+ * Run one checkpoint snapshot live: each declared probe runs read-only via the detached
  * primitive; its stdout is literal-scrubbed (provisioned values + the probe's declared redact
- * literals, folded into `scrub`) then pattern-redacted, then digested. Only the COMBINED digest
+ * literals, folded into `scrub`) then pattern-redacted, then digested. Only the combined digest
  * persists — never the raw value (the seed-step lockdown). Unique step names per snapshot prevent
  * stale-status reuse across snapshots.
  */
@@ -39,7 +39,7 @@ export async function runCheckpointSnapshot(args) {
         deltaFromPrev: args.prevDigest !== undefined && digest !== args.prevDigest,
     };
 }
-/** sha256-16 over the ordered seed-step command digests — the seeded-state RECIPE identity. */
+/** sha256-16 over the ordered seed-step command digests: the seeded-state recipe identity. */
 export function seedRecipeDigest(state) {
     const seed = state?.seed ?? [];
     return commandDigestOf(seed.map((step) => `${step.name}:${commandDigestOf(step.command)}`).join("\n"));

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

@@ -14,24 +14,25 @@ export interface SubjectComms {
 }
 export declare function subjectCommsOf(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass): SubjectComms;
 /**
- * ADOPTER-HOSTED ingress (#328): on the external-public plane the harness provisions nothing, so
- * it cannot host a catch — but the OPERATOR can, and then humanish still does every other part of
+ * Adopter-hosted ingress (#328): on the external-public plane the harness provisions nothing, so
+ * it cannot host a catch. The operator can, and then humanish still does every other part of
  * the funnel: it tells each persona its address and inbox URL, drains the declared catch over
  * HTTP at teardown, and writes the same digest-only evidence. Declaring `external` is what turns
  * the previously-inert block into a working one. Returns an error message when the declared catch
  * does not answer as a humanish catch.
  */
-export declare function prepareExternalComms(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[]): Promise<{
+export declare function prepareExternalComms(config: Pick<LabConfig, "comms">, planeClass: ConcurrentSharedWorldPlaneClass, dryRun: boolean, warnings: string[], env: Record<string, string | undefined>): Promise<{
     ok: true;
     wiring: ExternalCommsWiring | undefined;
 } | {
     ok: false;
+    code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_TOKEN_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE";
     message: string;
 }>;
 /**
  * Off-app comms evidence (#297): drain everything the in-sandbox catch captured, route it into a
  * host fake inbox addressed to the declared recipients, and write the run-level digest-only thread
- * artifact — while the subject is STILL alive, before it is killed. Wrapped so a drain error
+ * artifact while the subject is still alive, before it is killed. Wrapped so a drain error
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
  * the thread's path when one was written.
  */

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

@@ -1,17 +1,18 @@
 // Off-app comms for the concurrent shared-world route: which email catch a plane gets (in the
 // subject sandbox, or adopter-hosted), and the drains that match captured mail to the seats'
 // declared inboxes and write the digest-only thread.
+import { catchTokenOf, catchTokenRefusal, collectExternalCommsEvidence, } from "../../comms/external-evidence.js";
 import { FakeInbox } from "../../comms/fake-inbox.js";
 import { prepareReceivingRun } from "../../comms/receiving-runtime.js";
-import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, collectExternalCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
+import { DEFAULT_SANDBOX_CATCH_PORT, collectCommsThread, externalCatchHealthy, externalInboxUrl, } from "../../comms/sandbox-catch.js";
 import { redactText, toErrorMessage } from "../../evidence/redaction.js";
 import { writeContainedOutputFile } from "../../run/contained-output.js";
 import { addressedRecipients } from "../../lab/parse/comms.js";
-// Off-app comms (#297): on the provisioned-getHost plane the harness owns the ONE subject sandbox, so
-// it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated ENTIRELY
+// Off-app comms (#297): on the provisioned-getHost plane the harness owns the one subject sandbox, so
+// it can redirect the app's email-API sends into an in-sandbox catch and evidence them. Gated entirely
 // on config.comms — no comms declared → zero change. The base-URL env is injected into the subject
 // sandbox at create (fixed port known up front); the catch is deployed before serve; the drain + digest
-// evidence run at subject teardown, then register run-level in the bundle. NOT available on the
+// evidence run at subject teardown, then register run-level in the bundle. Unavailable on the
 // external-public plane (the app is an operator-owned deployment the harness never provisions).
 export function subjectCommsOf(config, planeClass) {
     const commsEmail = planeClass === "provisioned-getHost" && config.comms?.email?.kind === "fake"
@@ -26,14 +27,14 @@ export function subjectCommsOf(config, planeClass) {
     return { email: commsEmail, port: commsPort, env: commsEnv };
 }
 /**
- * ADOPTER-HOSTED ingress (#328): on the external-public plane the harness provisions nothing, so
- * it cannot host a catch — but the OPERATOR can, and then humanish still does every other part of
+ * Adopter-hosted ingress (#328): on the external-public plane the harness provisions nothing, so
+ * it cannot host a catch. The operator can, and then humanish still does every other part of
  * the funnel: it tells each persona its address and inbox URL, drains the declared catch over
  * HTTP at teardown, and writes the same digest-only evidence. Declaring `external` is what turns
  * the previously-inert block into a working one. Returns an error message when the declared catch
  * does not answer as a humanish catch.
  */
-export async function prepareExternalComms(config, planeClass, dryRun, warnings) {
+export async function prepareExternalComms(config, planeClass, dryRun, warnings, env) {
     const externalComms = planeClass === "external-public" ? config.comms?.email?.external : undefined;
     const externalCommsEmail = externalComms ? config.comms?.email : undefined;
     if (config.comms?.email?.kind === "fake" &&
@@ -44,12 +45,20 @@ export async function prepareExternalComms(config, planeClass, dryRun, warnings)
     if (!externalComms || !externalCommsEmail)
         return { ok: true, wiring: undefined };
     const inboxUrl = externalInboxUrl(externalComms);
-    // Fail closed BEFORE any actor sandbox is created: a comms lab whose catch is unreachable
-    // collects nothing while every lane still spends. The probe asserts OUR service marker in
+    const tokenRefusal = catchTokenRefusal(catchTokenOf(externalComms, env));
+    if (tokenRefusal !== undefined)
+        return {
+            ok: false,
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_TOKEN_INVALID",
+            message: tokenRefusal,
+        };
+    // Fail closed before any actor sandbox is created: a comms lab whose catch is unreachable
+    // collects nothing while every participant still spends. The probe asserts our service marker in
     // /health, so an adopter's proxy answering 200 for everything cannot pass for a catch.
     if (!dryRun && !(await externalCatchHealthy(externalComms))) {
         return {
             ok: false,
+            code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE",
             message: `The external comms catch or inbox is unreachable or incompatible (GET /health must identify humanish-comms-catch and advertise recipient-inbox-v1). Update humanish on the catch host and restart it with \`humanish comms catch\` on that host, or drop comms.email to run without the inbox funnel.`,
         };
     }
@@ -58,7 +67,7 @@ export async function prepareExternalComms(config, planeClass, dryRun, warnings)
 /**
  * Off-app comms evidence (#297): drain everything the in-sandbox catch captured, route it into a
  * host fake inbox addressed to the declared recipients, and write the run-level digest-only thread
- * artifact — while the subject is STILL alive, before it is killed. Wrapped so a drain error
+ * artifact while the subject is still alive, before it is killed. Wrapped so a drain error
  * never blocks teardown (invariant: all sandboxes torn down by id in the plane's finally). Returns
  * the thread's path when one was written.
  */
@@ -101,37 +110,15 @@ export async function drainSubjectComms(ctx, commsEmail, subjectShell, deployedC
  * masks the run's own outcome. Returns the thread's path when one was written.
  */
 export async function drainExternalComms(ctx, comms) {
-    const { env, runPaths, warnings } = ctx;
-    const externalComms = comms.external;
-    const externalCommsEmail = comms.email;
-    try {
-        const commsChannel = new FakeInbox();
-        const commsInboxes = [];
-        for (const recipient of addressedRecipients(externalCommsEmail)) {
-            commsInboxes.push(await commsChannel.provisionAddress(recipient.participantId, recipient.address));
-        }
-        const authToken = externalComms.authTokenEnv === undefined ? undefined : env[externalComms.authTokenEnv];
-        const collected = await collectExternalCommsThread({
-            external: { ...externalComms, ...(authToken === undefined ? {} : { authToken }) },
-            channel: commsChannel,
-            inboxes: commsInboxes,
-        });
-        if (collected.artifact) {
-            const path = "comms/thread.json";
-            await writeContainedOutputFile(runPaths, path, `${JSON.stringify(collected.artifact, null, 2)}\n`, "utf8");
-            return path;
-        }
-        else if (collected.captured > 0) {
-            warnings.push(`Comms catch captured ${collected.captured} email send(s) but none matched a declared recipient inbox — no comms evidence written. Declare comms.email.recipients[].address to match the address the app sends to.`);
-        }
-        else {
-            warnings.push(`Comms catch captured ZERO email sends — your app never delivered mail through the catch at ${externalComms.catchBaseUrl}. Verify the app's email-API base URL points at it and that the flow reached an email step.`);
-        }
-    }
-    catch (error) {
-        warnings.push(`Comms evidence collection failed against the adopter-hosted catch (run continues): ${redactText(toErrorMessage(error))}`);
-    }
-    return undefined;
+    const { path, warnings } = await collectExternalCommsEvidence({
+        external: comms.external,
+        email: comms.email,
+        env: ctx.env,
+        runPaths: ctx.runPaths,
+        knownSecretValues: ctx.knownSecretValues,
+    });
+    ctx.warnings.push(...warnings);
+    return path;
 }
 /** What receiving guards: the lab's email declaration and the subject env names and values. */
 export function receivingSourceOf(residual, env) {

package/dist/routes/shared-world/external-public.d.ts

@@ -11,11 +11,11 @@ export interface ExternalPublicPlaneOutcome {
     commsArtifactPath: string | undefined;
 }
 /**
- * The operator-DECLARED origin (from subject.appUrl) — recorded for evidence/reference ONLY. The
- * operator-OWNERSHIP claim rests on the subject.publicTarget.authorized attestation + this declared
- * appUrl, NOT on digest equality (blocker 2): a normal cross-origin redirect (apex->www, http->https;
- * lobby-trivia.example.test 307-redirects) makes the seats' OBSERVED origin differ from the declared one, which
- * is expected and MUST NOT fail the run. Persisted digest-only (never the raw origin).
+ * The operator-declared origin (from subject.appUrl), recorded for evidence and reference only. The
+ * operator-ownership claim rests on the subject.publicTarget.authorized attestation + this declared
+ * appUrl; digest equality plays no part (blocker 2): a normal cross-origin redirect (apex->www, http->https;
+ * lobby-trivia.example.test 307-redirects) makes the seats' observed origin differ from the declared one, which
+ * is expected and must not fail the run. Persisted digest-only (never the raw origin).
  */
 export declare function declaredOriginDigestOf(publicAppUrl: string): string | undefined;
 export declare function runExternalPublicPlane(ctx: PlaneContext, live: LiveParticipants, inbox: ExternalCommsWiring | undefined): Promise<ExternalPublicPlaneOutcome>;