humanish 0.105.0 → 0.106.0

package/dist/observer/data.d.ts

@@ -0,0 +1,115 @@
+import { type ActorEnding } from "../actors/stop-cause.js";
+import type { RunBundle, RunCostSummary, RunEvent, RunSimulation } from "../run/bundle.js";
+import type { RunStream, RunStreamKind } from "../run/streams.js";
+export declare const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
+interface ObserverArtifactLink {
+    label: string;
+    href: string;
+    kind: string;
+}
+export interface ObserverData {
+    schema: typeof OBSERVER_DATA_SCHEMA;
+    schemaVersion: 1;
+    generatedAt: string;
+    /** Served-only liveness observation. Never a replacement for the recorded evidence verdict. */
+    runtime?: {
+        state: "running" | "finished" | "interrupted" | "unknown";
+        observedAt: string;
+        source: "local-run-status";
+    };
+    run: {
+        runId: string;
+        mode: RunBundle["mode"];
+        status: RunBundle["review"]["verdict"];
+        title: string;
+        createdAt: string;
+        simCount: number;
+        persona: RunBundle["persona"];
+        scenario: RunBundle["scenario"];
+        packageName: string | null;
+        redaction: RunBundle["redaction"];
+        lifecycle: RunBundle["lifecycle"];
+        knownGaps: string[];
+        /**
+         * What happened to the PARTICIPANTS, with the denominator attached. `status` above collapses the
+         * run to one word for a gate; this is the study result, and it is what the person watching
+         * through the glass actually wants to know. Absent on a bundle with no participants.
+         *
+         * A viewing room that shows only vivid moments manufactures certainty from n=1 — so the count
+         * travels with the outcome here, always (docs/principles/three-roles.md).
+         */
+        participants?: RunBundle["review"]["participants"];
+        /** The same thing as one readable line, so a renderer cannot accidentally show a number
+         *  without its denominator. */
+        participantsLine?: string;
+        /** The study's per-task completion rates (#414), when the lab declared a protocol. */
+        tasks?: RunBundle["review"]["tasks"];
+        /** Pre-formatted like participantsLine, denominator on every number. */
+        tasksLine?: string;
+    };
+    summary: {
+        streams: number;
+        byKind: Record<RunStreamKind, number>;
+        active: number;
+        blocked: number;
+        warnings: number;
+    };
+    laneGroups: ObserverLaneGroup[];
+    /**
+     * OPTIONAL run-level cost ESTIMATE projected straight through from the bundle
+     * (humanish.run-cost-summary.v1). Absent when the bundle carries none. The Observer LABELS every
+     * figure as estimated (rates as of <asOf>) and never presents it as an authoritative charge.
+     */
+    cost?: RunCostSummary;
+    streams: ObserverStream[];
+    events: RunEvent[];
+    artifactLinks: ObserverArtifactLink[];
+    publicSafety: {
+        publishable: false;
+        note: string;
+        /**
+         * ADDITIVE + OPTIONAL (#584): the result of verification at static render or
+         * export time. Unverified projections omit this field. The timestamp records
+         * that check; it is not an assertion about subsequent file changes.
+         */
+        share?: {
+            status: "share_ready" | "local_only" | "blocked";
+            verifiedAt: string;
+            reasons: string[];
+        };
+    };
+    raw: {
+        bundleSchema: string;
+        artifactRoot: string;
+    };
+}
+export interface ObserverStream extends RunStream {
+    /** Only the attached server may grant provider-origin access for a live desktop iframe. */
+    embed?: NonNullable<RunStream["embed"]> & {
+        runtimeDesktop?: true;
+    };
+    /** Participant-facing status. The actor and simulation retain their original protocol status. */
+    status: RunStream["status"];
+    /** Precise recorded interruption; absent when the source carries no cause. */
+    ending?: ActorEnding;
+    sim: RunSimulation;
+    kindLabel: string;
+    statusLabel: string;
+    terminalPlain: string;
+    timeline: RunEvent[];
+}
+/** Discard a forged or stale runtime grant before projecting persisted evidence. */
+export declare function recordedStreamEmbed(embed: NonNullable<RunStream["embed"]>): NonNullable<RunStream["embed"]>;
+interface ObserverLaneGroup {
+    roleId: string;
+    simId: string;
+    streamId: string;
+    status: string;
+    actorType?: string;
+    surface?: string;
+    caseGroup?: string;
+}
+export declare function buildObserverData(bundle: RunBundle, generatedAt?: string): ObserverData;
+/** Refresh presentation from recorded actor evidence, including older exported snapshots. */
+export declare function withObserverEndings(data: ObserverData): ObserverData;
+export {};

package/dist/observer/data.js

@@ -0,0 +1,258 @@
+import { actorEnding } from "../actors/stop-cause.js";
+import { isCommsReceivingEvidence, receivingAnalysisContext } from "../comms/receiving-evidence.js";
+import { formatParticipantOutcomes, formatStudyTaskFunnel, participantOutcomeDetails, withCuaReviewProvenance, } from "../run/outcomes.js";
+import { cuaGoalSource, CUA_COMPLETION_NOTE } from "../actors/goal-source.js";
+export const OBSERVER_DATA_SCHEMA = "humanish.observer-data.v1";
+/** Discard a forged or stale runtime grant before projecting persisted evidence. */
+export function recordedStreamEmbed(embed) {
+    if (!embed)
+        return embed;
+    const { runtimeDesktop: _runtimeGrant, ...recorded } = embed;
+    return recorded;
+}
+const allKinds = [
+    "ui",
+    "browser",
+    "terminal",
+    "tui",
+    "codex-ui",
+    "artifact",
+    "summary",
+];
+export function buildObserverData(bundle, generatedAt = new Date().toISOString()) {
+    const byKind = Object.fromEntries(allKinds.map((kind) => [kind, 0]));
+    const events = [...(bundle.events ?? [])];
+    // Analysis cites this source-backed aggregate as context, not a participant
+    // action. Retain its identity for evidence navigation without inventing a
+    // timestamp, capture, or actor-trace entry. Raw provider/message data is never
+    // part of this projection, including on the best-effort live polling path.
+    const receiving = isCommsReceivingEvidence(bundle.commsReceiving)
+        ? bundle.commsReceiving
+        : undefined;
+    const streams = (bundle.streams ?? []).map((stream) => {
+        const sim = bundle.simulations.find((candidate) => candidate.id === stream.simId) ??
+            fallbackSimulation(bundle, stream);
+        // A natural session can finish its protocol while the participant explicitly reports a
+        // blocker (#690). Match the review's typed-outcome rule without rewriting the raw trace or
+        // guessing from prose. Never turn an active or failed harness into a participant outcome.
+        const status = (stream.status === "passed" || stream.status === "complete") &&
+            stream.actor?.completionReason === "goal_satisfied" &&
+            stream.actor.declaredOutcome === "blocked"
+            ? "blocked"
+            : stream.status;
+        byKind[stream.kind] += 1;
+        return {
+            ...stream,
+            ...(stream.embed === undefined ? {} : { embed: recordedStreamEmbed(stream.embed) }),
+            status,
+            sim,
+            kindLabel: kindLabel(stream.kind),
+            statusLabel: statusLabel(status),
+            terminalPlain: stripAnsi(stream.terminal?.tail ?? ""),
+            timeline: [
+                ...events.filter((event) => event.simId === sim.id || event.streamId === stream.id),
+                ...(receiving
+                    ? [
+                        {
+                            id: `comms-receiving-${stream.id}`,
+                            at: "",
+                            level: "info",
+                            type: "Harness email receiving (count-only context)",
+                            message: receivingAnalysisContext(receiving, stream.laneId),
+                            streamId: stream.id,
+                        },
+                    ]
+                    : []),
+            ],
+        };
+    });
+    const warnings = events.filter((event) => event.level === "warn").length;
+    const blocked = streams.filter((stream) => stream.status === "blocked" || stream.status === "failed" || stream.status === "timed_out").length;
+    const active = streams.filter((stream) => stream.status === "running" || stream.status === "preparing").length;
+    return withObserverEndings({
+        schema: OBSERVER_DATA_SCHEMA,
+        schemaVersion: 1,
+        generatedAt,
+        run: {
+            runId: bundle.runId,
+            mode: bundle.mode,
+            status: bundle.review.verdict,
+            title: `${bundle.scenario.title} - ${bundle.persona.name}`,
+            createdAt: bundle.createdAt,
+            simCount: bundle.simCount ?? bundle.simulations.length,
+            persona: bundle.persona,
+            scenario: bundle.scenario,
+            packageName: bundle.source.packageName,
+            redaction: bundle.redaction,
+            lifecycle: bundle.lifecycle,
+            knownGaps: withCuaReviewProvenance(bundle.review, bundle.streams).gaps,
+            ...(bundle.review.participants === undefined
+                ? {}
+                : {
+                    participants: bundle.review.participants,
+                }),
+            ...(bundle.review.tasks === undefined
+                ? {}
+                : {
+                    tasks: bundle.review.tasks,
+                    tasksLine: formatStudyTaskFunnel(bundle.review.tasks),
+                }),
+        },
+        summary: {
+            streams: streams.length,
+            byKind,
+            active,
+            blocked,
+            warnings,
+        },
+        laneGroups: buildLaneGroups(bundle),
+        ...(bundle.cost === undefined ? {} : { cost: bundle.cost }),
+        streams,
+        events,
+        artifactLinks: [
+            { label: "run bundle", href: "../run.json", kind: "bundle" },
+            { label: "review JSON", href: "../review.json", kind: "review" },
+            { label: "review Markdown", href: "../review.md", kind: "review" },
+            { label: "event log", href: "../events.ndjson", kind: "events" },
+            { label: "observer data", href: "observer-data.json", kind: "observer" },
+            ...(bundle.adapterArtifacts ?? []).map((artifact) => ({
+                label: artifact.label,
+                href: `../${artifact.path}`,
+                kind: artifact.kind,
+            })),
+        ],
+        publicSafety: {
+            publishable: false,
+            note: "Observer artifacts are local evidence. Before filing a public issue, use `humanish feedback issue` so redaction and public-safety checks gate the payload.",
+        },
+        raw: {
+            bundleSchema: bundle.schema,
+            artifactRoot: bundle.artifactRoot,
+        },
+    });
+}
+/** Refresh presentation from recorded actor evidence, including older exported snapshots. */
+export function withObserverEndings(data) {
+    const streams = (data.streams ?? []).map(({ ending: _previousEnding, ...stream }) => {
+        const ending = actorEnding(stream.actor);
+        const source = cuaGoalSource(stream.actor, stream.status);
+        return {
+            ...stream,
+            ...(ending === undefined ? {} : { ending }),
+            ...((stream.status === "passed" || stream.status === "complete") && source !== undefined
+                ? {
+                    statusLabel: source === "participant_report"
+                        ? "Reported complete"
+                        : source === "condition_matched"
+                            ? "Condition matched"
+                            : "Completion source unavailable",
+                }
+                : {}),
+            ...(stream.status === "incomplete" || (ending !== undefined && stream.status === "abandoned")
+                ? { statusLabel: "Interrupted" }
+                : {}),
+        };
+    });
+    const details = participantOutcomeDetails(streams);
+    return {
+        ...data,
+        streams,
+        run: {
+            ...data.run,
+            ...(data.run.participants !== undefined &&
+                data.run.participants.reachedGoal > 0 &&
+                details.some((entry) => entry.goalSource !== undefined)
+                ? {
+                    knownGaps: [
+                        ...data.run.knownGaps.filter((gap) => gap !== CUA_COMPLETION_NOTE),
+                        CUA_COMPLETION_NOTE,
+                    ],
+                }
+                : {}),
+            ...(data.run.participants === undefined
+                ? {}
+                : {
+                    participantsLine: formatParticipantOutcomes(data.run.participants, details),
+                }),
+        },
+    };
+}
+function buildLaneGroups(bundle) {
+    const outcomes = new Map((bundle.sharedWorld?.outcomes ?? []).map((outcome) => [outcome.roleId, outcome.status]));
+    return (bundle.sharedWorld?.laneWindows ?? []).map((lane) => ({
+        roleId: lane.roleId,
+        simId: lane.simId,
+        streamId: lane.streamId,
+        status: outcomes.get(lane.roleId) ?? lane.verdict,
+        ...(lane.actorType === undefined ? {} : { actorType: lane.actorType }),
+        ...(lane.surface === undefined ? {} : { surface: lane.surface }),
+        ...(lane.caseGroup === undefined ? {} : { caseGroup: lane.caseGroup }),
+    }));
+}
+function stripAnsi(value) {
+    return value
+        .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "")
+        .replace(/\u001b\][^\u0007]*(?:\u0007|\u001b\\)/g, "");
+}
+function fallbackSimulation(bundle, stream) {
+    return {
+        id: stream.simId,
+        index: bundle.simulations.length + 1,
+        personaId: bundle.persona.id,
+        scenarioId: bundle.scenario.id,
+        status: stream.status,
+        streamKind: stream.kind,
+        mode: "cli-sim",
+        progress: 0,
+        currentStep: "Unknown participant stream",
+        summary: "This stream did not include matching participant metadata.",
+        streamIds: [stream.id],
+        startedAt: bundle.createdAt,
+        updatedAt: stream.updatedAt,
+    };
+}
+function kindLabel(kind) {
+    switch (kind) {
+        case "ui":
+            return "UI";
+        case "browser":
+            return "Browser";
+        case "terminal":
+            return "CLI";
+        case "tui":
+            return "TUI";
+        case "codex-ui":
+            return "Codex UI";
+        case "artifact":
+            return "Artifact";
+        case "summary":
+            return "Summary";
+    }
+}
+function statusLabel(status) {
+    switch (status) {
+        case "contract_proof_only":
+            return "Contract proof";
+        case "preparing":
+            return "Preparing";
+        case "queued":
+            return "Queued";
+        case "running":
+            return "Running";
+        case "passed":
+            return "Passed";
+        // Participant outcomes read as what happened to a person, not as an error state.
+        case "abandoned":
+            return "Gave up";
+        case "incomplete":
+            return "Interrupted";
+        case "complete":
+            return "Complete";
+        case "blocked":
+            return "Blocked";
+        case "timed_out":
+            return "Timed out";
+        case "failed":
+            return "Failed";
+    }
+}

package/dist/observer/exposure.d.ts

@@ -0,0 +1,64 @@
+import { type ServeMode } from "./http.js";
+import { type ServeTunnel, type StartNgrokTunnelOptions } from "./tunnel.js";
+export type ExposureSurface = "serve" | "watch";
+export type ExposureErrorCode = "HUMANISH_SERVE_ALLOW_REQUIRES_OAUTH" | "HUMANISH_SERVE_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_SERVE_OPTION_CONFLICT" | "HUMANISH_SERVE_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_SERVE_EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE" | "HUMANISH_SERVE_EXPOSE_REQUIRES_ORIGIN" | "HUMANISH_WATCH_ALLOW_REQUIRES_OAUTH" | "HUMANISH_WATCH_OAUTH_REQUIRES_TUNNEL" | "HUMANISH_WATCH_OPTION_CONFLICT" | "HUMANISH_WATCH_TUNNEL_REQUIRES_EXPOSE" | "HUMANISH_WATCH_EXPOSE_REQUIRES_EDGE_AUTH" | "HUMANISH_WATCH_EXPOSE_REQUIRES_LIVE_FOLLOW" | "HUMANISH_WATCH_SAFE_NOT_APPLICABLE";
+export interface ExposureRequest {
+    expose: boolean;
+    tunnel?: "ngrok" | undefined;
+    tunnelDomain?: string | undefined;
+    oauth?: "google" | undefined;
+    allowEmails: string[];
+    allowDomains: string[];
+    publicUrl?: string | undefined;
+    safe: boolean;
+}
+export interface WatchLiveContext {
+    dryRun: boolean;
+    detach: boolean;
+    json: boolean;
+}
+export interface ExposurePlan {
+    exposed: boolean;
+    edgeAuthed: boolean;
+    mode: ServeMode;
+    safe: boolean;
+    tunnel?: "ngrok";
+    tunnelDomain?: string;
+    oauth?: {
+        provider: "google";
+        allowEmails: string[];
+        allowDomains: string[];
+    };
+    publicOrigin?: {
+        origin: string;
+        host: string;
+        scheme: "http" | "https";
+    };
+    warnings: string[];
+}
+export type ExposureValidation = {
+    ok: true;
+    plan: ExposurePlan;
+} | {
+    ok: false;
+    error: {
+        code: ExposureErrorCode;
+        message: string;
+    };
+};
+/** Why `watch` refuses `--safe`, on every watch path. */
+export declare const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.";
+export declare function validateExposure(surface: ExposureSurface, request: ExposureRequest, live?: WatchLiveContext): ExposureValidation;
+export interface ExposableServer {
+    readonly port: number;
+    readonly url: string;
+    addPublicOrigin(origin: string): void;
+}
+export interface ExposureResult {
+    tunnel?: ServeTunnel;
+    publicUrl?: string;
+    warnings: string[];
+}
+export declare function startExposedObserver(server: ExposableServer, plan: ExposurePlan, deps?: {
+    startTunnel?: (options: StartNgrokTunnelOptions) => Promise<ServeTunnel>;
+}): Promise<ExposureResult>;

package/dist/observer/exposure.js

@@ -0,0 +1,143 @@
+// Shared fail-closed exposure validation + tunnel orchestration for BOTH `serve` (a library of
+// finished runs) and `watch` (one live run). Exposure auth is TUNNEL-EDGE only: humanish carries no
+// in-process auth. Exposure is admitted only behind edge auth (ngrok --oauth google, or an operator
+// --public-url they secure) OR, for serve, behind --safe (share_ready runs only). A live watch run
+// is never share_ready (raw, unverified screenshots), so watch --expose ALWAYS requires edge auth.
+//
+// This module is pure with respect to the fail-closed matrix (validateExposure) and thin over the
+// tunnel launcher (startExposedObserver), so the CLI just maps flags in and results out.
+import { parsePublicOrigin } from "./http.js";
+import { startNgrokTunnel } from "./tunnel.js";
+/** Why `watch` refuses `--safe`, on every watch path. */
+export const WATCH_SAFE_NOT_APPLICABLE_MESSAGE = "watch streams a single live run that is never share_ready; --safe (a share_ready library filter) applies to `serve`, not `watch`. Restrict viewers with edge auth: --allow-email / --allow-domain.";
+function code(surface, suffix) {
+    return `HUMANISH_${surface.toUpperCase()}_${suffix}`;
+}
+export function validateExposure(surface, request, live) {
+    const fail = (suffix, message) => ({
+        ok: false,
+        error: { code: code(surface, suffix), message },
+    });
+    // Structural guards (both surfaces), in the fail-closed order documented in the matrix. These run
+    // before any bind/spawn so a mis-configured exposure aborts before sandbox/provider spend.
+    if ((request.allowEmails.length > 0 || request.allowDomains.length > 0) && !request.oauth) {
+        return fail("ALLOW_REQUIRES_OAUTH", "--allow-email/--allow-domain configure the ngrok edge OAuth allow-list; they require --oauth google.");
+    }
+    if (request.oauth && !request.tunnel) {
+        return fail("OAUTH_REQUIRES_TUNNEL", "--oauth turns on edge OAuth on the ngrok tunnel; it requires --tunnel ngrok (a --public-url operator brings their own edge auth).");
+    }
+    if (request.tunnel && request.publicUrl !== undefined) {
+        return fail("OPTION_CONFLICT", "Use either --tunnel or --public-url as the public origin, not both.");
+    }
+    if (request.tunnelDomain !== undefined && !request.tunnel) {
+        return fail("OPTION_CONFLICT", "--tunnel-domain requires --tunnel.");
+    }
+    const publicOrigin = request.publicUrl !== undefined ? parsePublicOrigin(request.publicUrl) : null;
+    if (request.publicUrl !== undefined && !publicOrigin) {
+        return fail("OPTION_CONFLICT", "--public-url must be an http(s) origin like https://observer.example.com.");
+    }
+    if (!request.expose) {
+        // Exposure flags without --expose are refused (no silent wide-open). On serve, --safe stays
+        // valid without --expose (a loopback share_ready filter); watch has nothing it could filter.
+        if (surface === "watch" && request.safe) {
+            return fail("SAFE_NOT_APPLICABLE", WATCH_SAFE_NOT_APPLICABLE_MESSAGE);
+        }
+        if (request.tunnel) {
+            return fail("TUNNEL_REQUIRES_EXPOSE", "--tunnel exposes the surface; declare that intent with --expose.");
+        }
+        if (request.publicUrl !== undefined) {
+            return fail("OPTION_CONFLICT", "--public-url only applies with --expose.");
+        }
+        return {
+            ok: true,
+            plan: {
+                exposed: false,
+                edgeAuthed: false,
+                mode: "loopback",
+                safe: request.safe,
+                warnings: [],
+            },
+        };
+    }
+    const oauth = request.oauth
+        ? {
+            provider: "google",
+            allowEmails: request.allowEmails,
+            allowDomains: request.allowDomains,
+        }
+        : undefined;
+    const edgeAuthed = Boolean(request.oauth) || Boolean(publicOrigin);
+    const warnings = [];
+    if (surface === "watch") {
+        // A live, in-progress run is never share_ready (raw screenshots, unverified), so --safe would
+        // admit nothing and expose nothing: watch --expose ALWAYS requires edge auth, and the live-follow
+        // preconditions are checked first so `--dry-run`/`--detach`/`--json` fail with the clearer reason.
+        if (live && (live.dryRun || live.detach || live.json)) {
+            return fail("EXPOSE_REQUIRES_LIVE_FOLLOW", "watch --expose streams a live desktop over an attached follow channel; it cannot combine with --dry-run, --detach, or --json.");
+        }
+        // --safe is a share_ready LIBRARY filter for `serve`; watch streams a single live run that is
+        // never share_ready, so --safe would silently do nothing here. Reject it rather than ignore it.
+        if (request.safe) {
+            return fail("SAFE_NOT_APPLICABLE", WATCH_SAFE_NOT_APPLICABLE_MESSAGE);
+        }
+        if (!edgeAuthed) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH", "watch --expose serves a live run that is never share_ready, so --safe cannot gate it; require edge auth: --tunnel ngrok --oauth google, or an operator-secured --public-url.");
+        }
+    }
+    else {
+        // serve: --expose must ALWAYS resolve to a reachable public origin (a tunnel or a --public-url),
+        // even under --safe. Without one the exposed server is an unreachable loopback no-op, so fail
+        // closed before the origin-less bind. When an origin IS present, keep the edge-auth-OR-safe gate.
+        if (!request.tunnel && !publicOrigin) {
+            return fail("EXPOSE_REQUIRES_ORIGIN", "--expose needs a declared public origin: pass --tunnel ngrok or --public-url <origin>.");
+        }
+        if (!edgeAuthed && !request.safe) {
+            return fail("EXPOSE_REQUIRES_EDGE_AUTH_OR_SAFE", "--expose opens a public URL to local run bundles; require edge auth (--oauth google with --tunnel, or a --public-url you secure) OR --safe (share_ready runs only).");
+        }
+    }
+    if (request.oauth && request.allowEmails.length === 0 && request.allowDomains.length === 0) {
+        warnings.push("ngrok --oauth google with NO --allow-email/--allow-domain lets ANY Google account that reaches the URL in; add at least one allow rule to restrict who can watch.");
+    }
+    const mode = edgeAuthed ? "exposed" : "share-safe-open";
+    return {
+        ok: true,
+        plan: {
+            exposed: true,
+            edgeAuthed,
+            mode,
+            safe: request.safe,
+            ...(request.tunnel ? { tunnel: request.tunnel } : {}),
+            ...(request.tunnelDomain ? { tunnelDomain: request.tunnelDomain } : {}),
+            ...(oauth ? { oauth } : {}),
+            ...(publicOrigin ? { publicOrigin } : {}),
+            warnings,
+        },
+    };
+}
+// Orchestrate the edge in front of an already-bound loopback server: spawn the ngrok tunnel (with
+// oauth/allow args) or declare the operator's --public-url, then extend the server's Host allowlist.
+// May throw a ServeTunnelError (ngrok missing/failed); callers close the loopback server on throw.
+export async function startExposedObserver(server, plan, deps = {}) {
+    const warnings = [...plan.warnings];
+    if (plan.tunnel === "ngrok") {
+        const startTunnel = deps.startTunnel ?? startNgrokTunnel;
+        const tunnel = await startTunnel({
+            port: server.port,
+            ...(plan.tunnelDomain ? { domain: plan.tunnelDomain } : {}),
+            ...(plan.oauth
+                ? {
+                    oauthProvider: plan.oauth.provider,
+                    oauthAllowEmails: plan.oauth.allowEmails,
+                    oauthAllowDomains: plan.oauth.allowDomains,
+                }
+                : {}),
+        });
+        server.addPublicOrigin(tunnel.url);
+        return { tunnel, publicUrl: tunnel.url.replace(/\/$/, ""), warnings };
+    }
+    if (plan.publicOrigin) {
+        server.addPublicOrigin(plan.publicOrigin.origin);
+        return { publicUrl: plan.publicOrigin.origin, warnings };
+    }
+    return { warnings };
+}

package/dist/observer/http.js

@@ -0,0 +1,50 @@
+// Shared HTTP hardening primitives for the serve surfaces. Extracted here so BOTH the live
+// Observer server (src/observer/render.ts) and the run-library server
+// (src/observer/serve.ts) can enforce the identical Host allowlist + security-header posture
+// without a module cycle. This file imports nothing from the serve modules.
+export function buildServeSecurityHeaders() {
+    return {
+        "cache-control": "no-store",
+        "referrer-policy": "no-referrer",
+        "x-content-type-options": "nosniff",
+        "x-frame-options": "DENY",
+        "content-security-policy": "frame-ancestors 'none'",
+        "x-robots-tag": "noindex, nofollow",
+    };
+}
+/** Saved artifacts may contain active HTML, SVG or XML. Give raw documents an
+ * opaque origin even on direct navigation, while preserving self-contained scripts.
+ * Generated Observer pages use buildServeSecurityHeaders instead. */
+export function buildArtifactSecurityHeaders() {
+    const headers = buildServeSecurityHeaders();
+    return {
+        ...headers,
+        "content-security-policy": `${headers["content-security-policy"]}; sandbox allow-scripts`,
+    };
+}
+export function hostAllowed(hostHeader, allowlist) {
+    return typeof hostHeader === "string" && allowlist.has(hostHeader.trim().toLowerCase());
+}
+export function parsePublicOrigin(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return null;
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        return null;
+    }
+    if ((parsed.pathname !== "/" && parsed.pathname !== "") ||
+        parsed.search ||
+        parsed.hash ||
+        !parsed.host) {
+        return null;
+    }
+    return {
+        origin: parsed.origin,
+        host: parsed.host.toLowerCase(),
+        scheme: parsed.protocol === "https:" ? "https" : "http",
+    };
+}