humanish 0.104.3 → 0.106.0

package/dist/lab/warnings.js

@@ -0,0 +1,338 @@
+import { isComputerUseComposition, isScriptedBrowserComposition, isSharedWorldComposition, isTerminalProductComposition, } from "./routing.js";
+import { declaredParticipantIds } from "./plan-participants.js";
+import { addressedRecipients } from "./parse/comms.js";
+import { focusOf, rosterOf } from "./parse/actors.js";
+// The computer-use and terminal routes consume mission/persona/model and laneFocus.instruction (they
+// compose the agent prompt and bundle provenance); laneFocus.id/label stay inert. On the computer-use
+// E2B route actors[0].lanes is consumed (the fan-out roster).
+const promptRoute = (routes) => routes.cua || routes.terminal;
+// The scripted-browser route consumes persona and count (trace/bundle provenance; surface roster).
+// The prompt fields can never act there: the scripted actor runs no model.
+const scriptedRoute = (routes) => !promptRoute(routes) && routes.scripted;
+const otherRoute = (routes) => !promptRoute(routes) && !routes.scripted;
+/** Rows for each actor, reported as `actors[<index>].<field>`, in this order per actor. */
+const ACTOR_ROWS = [
+    // Shared-world ONLY fields on the roster: per-role `entry` is inert anywhere else (invariant 6).
+    {
+        field: "lanes[].entry",
+        reason: "the per-role loopback entry is a shared-world capability; needs subject.topology: shared-world",
+        applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.entry !== undefined)) && !routes.shared,
+    },
+    // The host-seat marker acts ONLY on the external-public shared-world route; inert elsewhere.
+    {
+        field: "lanes[].host",
+        reason: "the designated host-participant marker; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
+        applies: (actor, routes) => Boolean(rosterOf(actor)?.some((entry) => entry.host === true)) && !routes.externalPublic,
+    },
+    {
+        field: "laneFocus.id",
+        applies: (actor, routes) => promptRoute(routes) && Boolean(focusOf(actor)?.id),
+    },
+    {
+        field: "laneFocus.label",
+        applies: (actor, routes) => promptRoute(routes) && Boolean(focusOf(actor)?.label),
+    },
+    {
+        field: "lanes",
+        reason: "fan-out is a computer-use route capability; terminal fan-out is a later slice",
+        applies: (actor, routes) => routes.terminal && Boolean(rosterOf(actor)),
+    },
+    {
+        field: "mission",
+        reason: "the scripted-browser actor runs no model",
+        applies: (actor, routes) => scriptedRoute(routes) && Boolean(actor.mission),
+    },
+    {
+        field: "laneFocus",
+        reason: "the scripted-browser actor runs no model",
+        applies: (actor, routes) => scriptedRoute(routes) && Boolean(focusOf(actor)),
+    },
+    {
+        field: "model",
+        reason: "the scripted-browser actor runs no model",
+        applies: (actor, routes) => scriptedRoute(routes) && Boolean(actor.model),
+    },
+    {
+        field: "lanes",
+        reason: "the scripted-browser route fans out via actors[0].count, not an actors[0].lanes roster",
+        applies: (actor, routes) => scriptedRoute(routes) && Boolean(rosterOf(actor)),
+    },
+    // On every other route the prompt fields, persona and the lane roster are inert.
+    { field: "mission", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.mission) },
+    {
+        field: "laneFocus",
+        applies: (actor, routes) => otherRoute(routes) && Boolean(focusOf(actor)),
+    },
+    { field: "persona", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.persona) },
+    { field: "model", applies: (actor, routes) => otherRoute(routes) && Boolean(actor.model) },
+    { field: "lanes", applies: (actor, routes) => otherRoute(routes) && Boolean(rosterOf(actor)) },
+];
+const TERMINAL_ONLY = "needs subject.source: terminal-product + a registered terminal actor";
+const RESERVED = "reserved for a later slice; not yet consumed";
+/** Rows for the rest of the config, reported after the actor rows, in this order. */
+const CONFIG_ROWS = [
+    // The computer-use routes consume (clone) subject.{serve,env,state,clone.depth}, and so does the
+    // scripted-browser route; on every other route they are inert.
+    {
+        field: "subject.clone.depth",
+        applies: (config, routes) => config.subject.clone?.depth !== undefined && !routes.cua && !routes.scripted,
+    },
+    {
+        field: "subject.serve",
+        applies: (config, routes) => Boolean(config.subject.serve) && !routes.cua && !routes.scripted,
+    },
+    {
+        field: "subject.env",
+        applies: (config, routes) => Boolean(config.subject.env) && !routes.cua && !routes.scripted,
+    },
+    {
+        field: "subject.state",
+        applies: (config, routes) => Boolean(config.subject.state) && !routes.cua && !routes.scripted,
+    },
+    // topology + checkpoint act ONLY on the shared-world route (#164); a set-but-unconsumed value
+    // (incl. an explicit per-lane-worlds, which the cua route already is by mechanism) warns inert.
+    {
+        field: "subject.topology",
+        reason: "drives behavior only on the shared-world route; needs subject.topology: shared-world + clone × e2b-desktop × a computer-use actor + a roster of ≥2 participants",
+        applies: (config, routes) => config.subject.topology !== undefined && !routes.shared,
+    },
+    {
+        field: "subject.state.checkpoint",
+        reason: "the shared-world state-checkpoint probe; needs subject.topology: shared-world",
+        applies: (config, routes) => config.subject.state?.checkpoint !== undefined && !routes.shared,
+    },
+    // publicTarget (the external-public ownership attestation) acts ONLY on the external-public
+    // shared-world route; inert elsewhere. (It is already parse-rejected on non-app-url sources.)
+    {
+        field: "subject.publicTarget",
+        reason: "the external-public ownership attestation; needs the external-public shared-world route: app-url × topology shared-world × allowPublicTargets",
+        applies: (config, routes) => config.subject.publicTarget !== undefined && !routes.externalPublic,
+    },
+    // exposure (the synthetic-subject attestation) acts ONLY on the shared-world route (the
+    // getHost-exposed plane) and on scripted clones; inert elsewhere.
+    {
+        field: "subject.exposure",
+        reason: "the synthetic-subject attestation for a getHost-exposed plane; needs shared-world or clone × e2b-desktop × scripted-browser",
+        applies: (config, routes) => config.subject.exposure !== undefined &&
+            !routes.shared &&
+            !(routes.scripted && config.subject.source === "clone"),
+    },
+    // comms.email drives the in-sandbox email/SMS catch, which needs a subject sandbox HUMANISH
+    // provisions (clone or local-tree) so it holds a handle to host the catch. On an app-url /
+    // operator-provided subject there is no such handle, so a declared comms block would silently
+    // collect nothing — a false green. Warn at parse time (fires on inspect + dry-run too).
+    {
+        field: "comms.email",
+        reason: "the in-sandbox email/SMS catch needs a harness-provisioned subject to host it — subject.source: clone or local-tree; on an app-url or operator-provided subject humanish holds no sandbox handle. Declare `comms.email.external` to run the catch yourself: humanish then points the persona at your inbox, drains your catch, and writes the same evidence — see #328",
+        applies: (config) => config.comms?.email?.kind === "fake" &&
+            config.comms.email.external === undefined &&
+            config.subject.source !== "clone" &&
+            config.subject.source !== "local-tree",
+    },
+    // The reverse mis-config: declaring an adopter-hosted catch on a route where humanish provisions
+    // the subject itself. Two catches would exist and the app would point at humanish's, so the
+    // declared external one would silently collect nothing.
+    {
+        field: "comms.email.external",
+        reason: "this subject is harness-provisioned, so humanish hosts the catch itself and injects its URL; an adopter-hosted catch would receive nothing. Drop `external` here, or move the lab to an app-url/operator-provisioned subject",
+        applies: (config) => Boolean(config.comms?.email?.external) &&
+            (config.subject.source === "clone" || config.subject.source === "local-tree"),
+    },
+    // clone.keep IS consumed on the cua route (honored on FAILURE: the sandbox is left up to debug
+    // a failed install/boot; otherwise always killed). clone.fanout is REJECTED on the cua route
+    // (a hard parse error above), so it can never reach this warning list there.
+    {
+        field: "execution.timeoutMs",
+        applies: (config, routes) => !routes.cua &&
+            !routes.scripted &&
+            !routes.terminal &&
+            config.execution?.timeoutMs !== undefined,
+    },
+    {
+        field: "execution.completionTimeoutMs",
+        applies: (config) => config.execution?.completionTimeoutMs !== undefined,
+    },
+    // execution.concurrency is CONSUMED on the cua route (it bounds in-flight fan-out lanes);
+    // inert (warned) everywhere else.
+    {
+        field: "execution.concurrency",
+        applies: (config, routes) => config.execution?.concurrency !== undefined && !routes.cua,
+    },
+    // execution.caps is CONSUMED on the cua route (maxUsd is the fail-closed spend abort); inert
+    // (warned) everywhere else so a misplaced budget field is never trusted to cap a route it cannot.
+    {
+        field: "execution.caps",
+        reason: "the fail-closed spend abort is a computer-use route capability; needs a computer-use actor on e2b-desktop",
+        applies: (config, routes) => Boolean(config.execution?.caps) && !routes.cua,
+    },
+    // terminal-product consumes subject.product, scenario.caps, execution.{terminal,runtimeAuth}:
+    // dry-run records the contract; live execution enforces caps and command-scoped auth. On every
+    // OTHER route they are inert and must warn so a
+    // misplaced safety/budget field is never trusted to do something it cannot (invariant 6).
+    {
+        field: "subject.product",
+        reason: "needs subject.source: terminal-product or desktop-cli with the matching actor",
+        applies: (config, routes) => Boolean(config.subject.product) &&
+            !routes.terminal &&
+            config.subject.source !== "desktop-cli",
+    },
+    {
+        field: "scenario.caps",
+        reason: TERMINAL_ONLY,
+        applies: (config, routes) => Boolean(config.scenario?.caps) && !routes.terminal,
+    },
+    // The study-level budget is a CUA-route capability; the terminal route is a single agent whose
+    // maxUsd already caps the whole run, so a maxTotalUsd there would be trusted and unenforced.
+    {
+        field: "scenario.caps.maxTotalUsd",
+        reason: "the study-level budget is a computer-use route capability; the terminal route's maxUsd already caps the whole run",
+        applies: (config, routes) => config.scenario?.caps?.maxTotalUsd !== undefined && routes.terminal,
+    },
+    {
+        field: "execution.terminal",
+        reason: TERMINAL_ONLY,
+        applies: (config, routes) => Boolean(config.execution?.terminal) && !routes.terminal,
+    },
+    {
+        field: "execution.runtimeAuth",
+        reason: TERMINAL_ONLY,
+        applies: (config, routes) => config.execution?.runtimeAuth !== undefined && !routes.terminal,
+    },
+    {
+        field: "execution.runtime",
+        reason: TERMINAL_ONLY,
+        applies: (config, routes) => config.execution?.runtime !== undefined && !routes.terminal,
+    },
+    // execution.desktop.* stays inert on the scripted route by design: device presets belong to
+    // the cua desktop; scripted surfaces are the driver's fixed desktop/mobile viewports, where
+    // isMobile/DSF genuinely render via playwright emulation.
+    {
+        field: "execution.desktop.resolution",
+        applies: (config, routes) => !routes.cua && Boolean(config.execution?.desktop?.resolution),
+    },
+    {
+        field: "execution.desktop.device",
+        applies: (config, routes) => !routes.cua && config.execution?.desktop?.device !== undefined,
+    },
+    {
+        field: "execution.desktop.browser",
+        applies: (config, routes) => !routes.hostedCuaBrowser && config.execution?.desktop?.browser !== undefined,
+    },
+    {
+        field: "execution.desktop.fidelity",
+        reason: "mobile emulation is applied only to computer-use participants in hosted Chromium on execution.target: e2b-desktop",
+        applies: (config, routes) => !routes.hostedCuaBrowser && config.execution?.desktop?.fidelity !== undefined,
+    },
+    {
+        field: "execution.desktop.sandboxTimeoutMs",
+        applies: (config, routes) => !routes.cua && config.execution?.desktop?.sandboxTimeoutMs !== undefined,
+    },
+    // execution.desktop.template (the custom E2B desktop image) is consumed ONLY where a desktop is
+    // actually created via Sandbox.create — the e2b-desktop computer-use routes (cua/shared-world/
+    // concurrent). It is INERT on every other route (incl. the in-process local-app cua route, which
+    // creates no desktop): warn so an unconsumed template is never silently ignored (invariant 6).
+    {
+        field: "execution.desktop.template",
+        reason: "the custom E2B desktop image is consumed only on execution.target: e2b-desktop computer-use routes that create a desktop; needs a computer-use actor on e2b-desktop",
+        applies: (config, routes) => config.execution?.desktop?.template !== undefined && !routes.createsE2BDesktop,
+    },
+    // No route reads codexAppServer since the route that consumed it was removed. The key still
+    // parses so older manifests load, so flag it wherever it is set.
+    {
+        field: "execution.desktop.codexAppServer",
+        reason: "no current route reads it",
+        applies: (config) => config.execution?.desktop?.codexAppServer !== undefined,
+    },
+    // scenario.ref is CONSUMED on the scripted-browser route (required there); forward-declared
+    // everywhere else.
+    {
+        field: "scenario.ref",
+        applies: (config, routes) => Boolean(config.scenario?.ref) && !routes.scripted,
+    },
+    { field: "scenario.inline", applies: (config) => Boolean(config.scenario?.inline) },
+    // review.{scoring,milestones,vocabulary} stay forward-declared (reserved for #319) on every route.
+    // review.scorer (#316) IS consumed (loaded + wired, or fail-closed at load) on every scorer-capable
+    // route, so it does not warn there; on the scripted-browser route the actor carries no scorer seam,
+    // so a declared scorer is flagged inert (the run also fails closed at load).
+    {
+        field: "review.scoring",
+        reason: RESERVED,
+        applies: (config) => Boolean(config.review?.scoring),
+    },
+    {
+        field: "review.milestones",
+        reason: RESERVED,
+        applies: (config) => Boolean(config.review?.milestones),
+    },
+    {
+        field: "review.vocabulary",
+        reason: RESERVED,
+        applies: (config) => Boolean(config.review?.vocabulary),
+    },
+    {
+        field: "review.scorer",
+        reason: "the scripted-browser actor has no adopter-scorer seam; declare it on a terminal / computer-use / shared-world route",
+        applies: (config, routes) => Boolean(config.review?.scorer) && routes.scripted,
+    },
+    { field: "personas", applies: (config) => Boolean(config.personas) },
+];
+function routesOf(config) {
+    const cua = isComputerUseComposition(config);
+    const scripted = isScriptedBrowserComposition(config);
+    const shared = isSharedWorldComposition(config);
+    return {
+        cua,
+        scripted,
+        terminal: isTerminalProductComposition(config),
+        shared,
+        externalPublic: shared && config.subject.source === "app-url",
+        hostedCuaBrowser: config.execution?.target === "e2b-desktop" && cua,
+        createsE2BDesktop: (cua || (scripted && config.subject.source === "clone")) &&
+            config.execution?.target === "e2b-desktop",
+    };
+}
+function rowLabel(row, prefix = "") {
+    return row.reason === undefined
+        ? `${prefix}${row.field}`
+        : `${prefix}${row.field} (${row.reason})`;
+}
+// Report fields that are present but not yet consumed by the engine, so a user never trusts a
+// setting that silently does nothing. Keeps the schema forward-correct AND honest.
+export function forwardDeclaredWarnings(config) {
+    const routes = routesOf(config);
+    const inert = [];
+    for (const [index, actor] of config.actors.entries()) {
+        for (const row of ACTOR_ROWS)
+            if (row.applies(actor, routes))
+                inert.push(rowLabel(row, `actors[${index}].`));
+    }
+    for (const row of CONFIG_ROWS)
+        if (row.applies(config, routes))
+            inert.push(rowLabel(row));
+    const warnings = inert.length === 0
+        ? []
+        : [
+            `Forward-declared fields are set but not yet consumed by the engine (planned for a later slice): ${inert.join(", ")}.`,
+        ];
+    // A declared cap below the seat count is legal but loud: the roster promises N live actors and
+    // the cap delivers waves of M. Say so up front (inspect + dry-run + run) — a green run in waves
+    // is otherwise indistinguishable from the all-live run the author meant (#350).
+    {
+        const participantCount = rosterOf(config.actors[0])?.length ?? config.actors[0]?.count ?? 1;
+        const cap = config.execution?.concurrency;
+        if (routes.cua && cap !== undefined && participantCount > 1 && cap < participantCount) {
+            warnings.push(`execution.concurrency ${cap} caps a ${participantCount}-participant roster: participants run in waves of ${cap}, never all live at once. Remove execution.concurrency (the default runs all ${participantCount} participants simultaneously) or set it to ${participantCount}; declare a lower cap only to bound simultaneous paid desktops.`);
+        }
+    }
+    // Partial email coverage is legal but loud (#351): a lane without an addressed recipient never
+    // hears an inbox exists, so an email-gated flow on that seat dead-ends by construction.
+    if (routes.cua && config.comms?.email?.recipients) {
+        const participantIds = declaredParticipantIds(config);
+        const covered = new Set(addressedRecipients(config.comms.email).map((recipient) => recipient.participantId));
+        const uncovered = participantIds.filter((id) => !covered.has(id));
+        if (covered.size > 0 && uncovered.length > 0 && participantIds.length > 1) {
+            warnings.push(`comms.email covers ${covered.size} of ${participantIds.length} participants; the uncovered participant(s) get no inbox and are never told one exists: ${uncovered.join(", ")}. Add addressed recipients for them if their flows need email.`);
+        }
+    }
+    return warnings;
+}

package/dist/observer/artifact.d.ts

@@ -0,0 +1,23 @@
+import type { LoadedAnalysis } from "../analysis/types.js";
+import { type ObserverData } from "./data.js";
+/**
+ * Resolve — and in a repo checkout, build — the Observer artifact BEFORE any run or
+ * lab work starts. A missing artifact must cost seconds at startup, never a completed
+ * session (a live lane spends real money before the render step would have noticed).
+ * Unconditional on purpose: the artifact is the only renderer now, so the fail-before-
+ * spend property this preflight bought under the flag matters more, not less.
+ */
+export declare function preflightObserverArtifact(): void;
+/** internal: exported for tests. Missing artifact, or any workspace source newer than it. */
+export declare function observerArtifactNeedsBuild(workspaceDir: string, artifactPath: string): boolean;
+/** Portable files store each exact raster once, outside the run-data JSON. */
+export type ObserverExportAssets = Record<string, {
+    mime: string;
+    base64: string;
+}>;
+/** Render current packaged UI around a validated/projected Observer snapshot. */
+export declare function renderObserverHtml(data: ObserverData, options?: {
+    snapshot?: boolean;
+    analysis?: LoadedAnalysis;
+    assets?: ObserverExportAssets;
+}): string;

package/dist/observer/artifact.js

@@ -0,0 +1,235 @@
+// The built Observer app and the HTML that carries a run's data into it. The app comes from the
+// package's dist/observer-app.html, or in a repo checkout is built from observer/ when missing or
+// stale, and is cached for the process. Run data and study analysis are embedded as JSON scripts.
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { projectShareCheckedAnalysis, studyAnalysisSharingProblems } from "../analysis/sharing.js";
+import { withObserverEndings } from "./data.js";
+const OBSERVER_DATA_PLACEHOLDER = "__HUMANISH_OBSERVER_DATA__";
+const OBSERVER_DATA_SLOT = `<script id="observer-data" type="application/json">${OBSERVER_DATA_PLACEHOLDER}</script>`;
+let cachedObserverArtifact = null;
+/**
+ * Resolve — and in a repo checkout, build — the Observer artifact BEFORE any run or
+ * lab work starts. A missing artifact must cost seconds at startup, never a completed
+ * session (a live lane spends real money before the render step would have noticed).
+ * Unconditional on purpose: the artifact is the only renderer now, so the fail-before-
+ * spend property this preflight bought under the flag matters more, not less.
+ */
+export function preflightObserverArtifact() {
+    loadObserverArtifact();
+}
+function loadObserverArtifact() {
+    if (cachedObserverArtifact !== null)
+        return cachedObserverArtifact;
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    // Published package: the root build ships the artifact at the dist/ root, one level above
+    // this module. Never auto-built: an installed package either carries it or is broken.
+    const packagedHtml = readObserverArtifact(path.join(moduleDir, "..", "observer-app.html"));
+    if (packagedHtml !== null) {
+        cachedObserverArtifact = packagedHtml;
+        return packagedHtml;
+    }
+    // Repo checkout (this module sits two levels under the root, in src/observer/ or
+    // dist/observer/): build the workspace on demand when it is missing or stale.
+    const repoRoot = path.join(moduleDir, "..", "..");
+    const workspaceDir = path.join(repoRoot, "observer");
+    const artifactPath = path.join(workspaceDir, "dist", "index.html");
+    if (existsSync(path.join(workspaceDir, "package.json"))) {
+        if (observerArtifactNeedsBuild(workspaceDir, artifactPath)) {
+            // Concurrent cold starts (parallel test workers, two watch processes launched
+            // together) must not race one `vite build` output: a reader can catch the
+            // artifact half-written. A mkdir lock serializes builders across processes;
+            // whoever loses the race re-checks staleness and usually just reads.
+            // The lock lives OUTSIDE dist/ (vite empties dist mid-build) and inside an
+            // ignored path so a crashed builder cannot dirty the tree.
+            const lockDir = path.join(workspaceDir, "node_modules", ".observer-build-lock");
+            mkdirSync(path.dirname(lockDir), { recursive: true });
+            const deadline = Date.now() + 120_000;
+            for (;;) {
+                try {
+                    mkdirSync(lockDir);
+                    break; // lock acquired — this process builds
+                }
+                catch {
+                    if (Date.now() > deadline)
+                        break; // stale lock: build anyway, last writer wins
+                    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 200);
+                    if (!observerArtifactNeedsBuild(workspaceDir, artifactPath)) {
+                        const built = readObserverArtifact(artifactPath);
+                        if (built !== null) {
+                            cachedObserverArtifact = built;
+                            return built;
+                        }
+                    }
+                }
+            }
+            try {
+                if (observerArtifactNeedsBuild(workspaceDir, artifactPath)) {
+                    process.stderr.write("observer: building the Observer artifact (observer/ workspace)…\n");
+                    try {
+                        // NODE_ENV is forced: Vite respects a preset NODE_ENV (test, development),
+                        // and a dev-flavored artifact embeds jsxDEV plus the builder's absolute
+                        // filesystem paths — which the run's public-safety scan then rightly rejects.
+                        execSync("pnpm --filter humanish-observer build", {
+                            cwd: repoRoot,
+                            stdio: ["ignore", "pipe", "inherit"],
+                            env: { ...process.env, NODE_ENV: "production" },
+                        });
+                    }
+                    catch {
+                        throw new Error("observer workspace build failed — run `pnpm --filter humanish-observer build` for the full output.");
+                    }
+                }
+            }
+            finally {
+                rmSync(lockDir, { force: true, recursive: true });
+            }
+        }
+        const html = readObserverArtifact(artifactPath);
+        if (html !== null) {
+            cachedObserverArtifact = html;
+            return html;
+        }
+    }
+    throw new Error("the Observer needs its prebuilt artifact (dist/observer-app.html in the package, observer/dist/index.html in a repo checkout); run `pnpm --filter humanish-observer build`, or reinstall the package.");
+}
+function readObserverArtifact(candidate) {
+    let html;
+    try {
+        html = readFileSync(candidate, "utf8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (!html.includes(OBSERVER_DATA_SLOT)) {
+        throw new Error(`Observer artifact at ${candidate} has no observer-data slot.`);
+    }
+    return html;
+}
+/** internal: exported for tests. Missing artifact, or any workspace source newer than it. */
+export function observerArtifactNeedsBuild(workspaceDir, artifactPath) {
+    let artifactMtime;
+    try {
+        artifactMtime = statSync(artifactPath).mtimeMs;
+    }
+    catch {
+        return true;
+    }
+    return newestSourceMtime(workspaceDir) > artifactMtime;
+}
+function newestSourceMtime(dir) {
+    let newest = 0;
+    let entries;
+    try {
+        entries = readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return newest;
+    }
+    for (const entry of entries) {
+        if (entry.name === "node_modules" || entry.name === "dist")
+            continue;
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            newest = Math.max(newest, newestSourceMtime(full));
+        }
+        else if (entry.isFile()) {
+            try {
+                newest = Math.max(newest, statSync(full).mtimeMs);
+            }
+            catch {
+                // A file vanishing mid-scan (editor save) just doesn't advance the clock.
+            }
+        }
+    }
+    return newest;
+}
+function renderExportAssets(assets) {
+    return Object.entries(assets)
+        .map(([hash, image]) => {
+        if (!/^[a-f0-9]{64}$/.test(hash) ||
+            !/^image\/(png|jpeg|gif|webp)$/.test(image.mime) ||
+            !/^[A-Za-z0-9+/]+={0,2}$/.test(image.base64))
+            throw new Error("Invalid portable raster");
+        return `<script id="humanish-image-${hash}" type="application/octet-stream" data-mime="${image.mime}">${image.base64}</script>`;
+    })
+        .join("");
+}
+function renderObserverAppHtml(data, snapshot, analysis, assets) {
+    const artifact = loadObserverArtifact();
+    // A renderer-owned boot marker, outside the untrusted run-data contract. Only
+    // portable HTML exports opt out of a live feed; ordinary served pages still poll.
+    return (snapshot
+        ? artifact.replace("</head>", '<meta name="humanish-observer-mode" content="snapshot"></head>')
+        : artifact)
+        .replace(OBSERVER_DATA_SLOT, () => `<script id="observer-data" type="application/json">${escapeJsonScript(data)}</script>`)
+        .replace(/<script id="study-analysis" type="application\/json">[\s\S]*?<\/script>/, () => `<script id="study-analysis" type="application/json">${escapeJsonScript(analysis)}</script>`)
+        .replace("</body>", () => `${renderExportAssets(assets)}</body>`)
+        .replace(/<title>[^<]*<\/title>/, () => `<title>humanish Observer — ${escapeHtml(data.run.runId)}</title>`);
+}
+/** Render current packaged UI around a validated/projected Observer snapshot. */
+export function renderObserverHtml(data, options = {}) {
+    let analysis = options.analysis ?? {
+        state: "none",
+        analysis: null,
+        corrections: [],
+        warnings: [],
+    };
+    // A portable snapshot cannot claim that a writer on another machine is still active.
+    if (options.snapshot === true &&
+        analysis.automatic &&
+        ["queued", "running"].includes(analysis.automatic.state)) {
+        analysis = {
+            ...analysis,
+            automatic: {
+                ...analysis.automatic,
+                state: "unknown",
+                reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN",
+            },
+        };
+    }
+    const sharing = studyAnalysisSharingProblems(analysis);
+    if (data.publicSafety && (sharing.sensitive || sharing.unverified)) {
+        const share = data.publicSafety.share;
+        data = {
+            ...data,
+            publicSafety: {
+                ...data.publicSafety,
+                share: {
+                    status: sharing.sensitive || share?.status === "blocked" ? "blocked" : "local_only",
+                    verifiedAt: share?.verifiedAt ?? new Date().toISOString(),
+                    reasons: [...new Set([...(share?.reasons ?? []), "ANALYSIS_UNVERIFIED"])],
+                },
+            },
+        };
+    }
+    return renderObserverAppHtml(withObserverEndings(data), options.snapshot === true, projectShareCheckedAnalysis(analysis), options.assets ?? {});
+}
+function escapeHtml(value) {
+    return value.replace(/[&<>"']/g, (char) => {
+        switch (char) {
+            case "&":
+                return "&amp;";
+            case "<":
+                return "&lt;";
+            case ">":
+                return "&gt;";
+            case '"':
+                return "&quot;";
+            default:
+                return "&#39;";
+        }
+    });
+}
+function escapeJsonScript(value) {
+    return JSON.stringify(value)
+        .replace(/</g, "\\u003c")
+        .replace(/>/g, "\\u003e")
+        .replace(/&/g, "\\u0026")
+        .replace(/\u2028/g, "\\u2028")
+        .replace(/\u2029/g, "\\u2029");
+}