humanish 0.104.3 → 0.106.0

package/dist/observer.js

@@ -1,947 +0,0 @@
-import { listenOnLoopback } from "./listen.js";
-import { execSync, spawn } from "node:child_process";
-import { constants as fsConstants, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync } from "node:fs";
-import { createServer } from "node:http";
-import { lstat, open, realpath } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { buildObserverData, recordedStreamEmbed, withObserverEndings } from "./observer-data.js";
-import { listRuns, loadRunBundlePrepared, verifyRunPrepared } from "./run.js";
-import { bindExistingRunArtifactPaths, isPathInside, isSafeRunIdSegment, resolveLatestRunDirectory, validatePreparedRunArtifactPaths } from "./run-paths.js";
-import { writeContainedOutputFile } from "./selected-output-paths.js";
-import { buildArtifactSecurityHeaders, buildServeSecurityHeaders, hostAllowed, parsePublicOrigin } from "./serve-http.js";
-import { isRunStatusRecord, RUN_STATUS_FILE, RUN_STATUS_STALE_MS } from "./run-status.js";
-import { loadStudyAnalysis } from "./study-analysis-store.js";
-import { isStudyAnalysisRecordPath, projectShareCheckedAnalysis, studyAnalysisSharingProblems } from "./study-analysis-sharing.js";
-export const OBSERVER_SCHEMA = "humanish.observer-result.v1";
-const observerRuntimeStreamUrls = new WeakMap();
-const observerPreparedRunPaths = new WeakMap();
-export function attachObserverRuntimeStreamUrls(result, streams) {
-    observerRuntimeStreamUrls.set(result, streams.filter((stream) => stream.streamId && stream.url));
-}
-export async function renderObserver(cwdInput, runInput, options = {}) {
-    const cwd = path.resolve(cwdInput);
-    let selection;
-    try {
-        if (options.expectedRun) {
-            const prepared = options.expectedRun;
-            if (runInput !== path.basename(prepared.physicalRunRoot)
-                || await realpath(cwd) !== path.dirname(path.dirname(prepared.physicalRunsRoot))) {
-                throw new Error("Observer source pin does not match the selected run.");
-            }
-            await validatePreparedRunArtifactPaths(prepared);
-            selection = { runId: runInput,
-                runRoot: { ...prepared.runRootIdentity, physicalPath: prepared.physicalRunRoot },
-                runsRoot: { ...prepared.runsRootIdentity, physicalPath: prepared.physicalRunsRoot } };
-        }
-        else {
-            selection = await resolveObserverRunSelection(cwd, runInput);
-        }
-    }
-    catch {
-        selection = null;
-    }
-    if (!selection) {
-        return observerRunError(cwd, runInput, "HUMANISH_RUN_NOT_FOUND", `Run not found: ${runInput}`);
-    }
-    let preparedRunPaths;
-    try {
-        const selectedPhysicalCwd = path.dirname(path.dirname(selection.runsRoot.physicalPath));
-        preparedRunPaths = options.expectedRun ?? await bindExistingRunArtifactPaths(selectedPhysicalCwd, selection.runId);
-        if (preparedRunPaths.physicalRunsRoot !== selection.runsRoot.physicalPath
-            || preparedRunPaths.physicalRunRoot !== selection.runRoot.physicalPath
-            || preparedRunPaths.runsRootIdentity.birthtimeNs !== selection.runsRoot.birthtimeNs
-            || preparedRunPaths.runsRootIdentity.dev !== selection.runsRoot.dev
-            || preparedRunPaths.runsRootIdentity.ino !== selection.runsRoot.ino
-            || preparedRunPaths.runRootIdentity.birthtimeNs !== selection.runRoot.birthtimeNs
-            || preparedRunPaths.runRootIdentity.dev !== selection.runRoot.dev
-            || preparedRunPaths.runRootIdentity.ino !== selection.runRoot.ino) {
-            throw new Error("Observer run selection changed physical identity.");
-        }
-    }
-    catch {
-        return observerRunError(cwd, runInput, "HUMANISH_INVALID_RUN_BUNDLE", "Observer run storage is unavailable or unsafe.");
-    }
-    await validatePreparedRunArtifactPaths(preparedRunPaths);
-    const selectedPhysicalCwd = path.dirname(path.dirname(selection.runsRoot.physicalPath));
-    const verified = await verifyRunPrepared(selectedPhysicalCwd, selection.runId, preparedRunPaths);
-    await validatePreparedRunArtifactPaths(preparedRunPaths);
-    if (!verified.ok && verified.recordingOk !== true) {
-        return observerRunError(cwd, runInput, verified.error?.code === "HUMANISH_RUN_NOT_FOUND" ? "HUMANISH_RUN_NOT_FOUND" : "HUMANISH_INVALID_RUN_BUNDLE", verified.error?.message ?? "Run bundle failed verification.");
-    }
-    const loaded = await loadRunBundlePrepared(selectedPhysicalCwd, preparedRunPaths);
-    await validatePreparedRunArtifactPaths(preparedRunPaths);
-    if (!loaded) {
-        return observerRunError(cwd, runInput, "HUMANISH_RUN_NOT_FOUND", `Run not found: ${runInput}`);
-    }
-    if (loaded.bundle.runId !== selection.runId
-        || await realpath(loaded.runDir) !== preparedRunPaths.physicalRunRoot) {
-        throw new Error("Observer output directory does not match the selected run.");
-    }
-    const observerPath = path.join(preparedRunPaths.physicalRunRoot, "observer", "index.html");
-    const analysis = projectShareCheckedAnalysis(await loadStudyAnalysis(preparedRunPaths));
-    const observerData = buildObserverData(loaded.bundle);
-    observerData.publicSafety.share = {
-        status: verified.shareSafety.status,
-        verifiedAt: new Date().toISOString(),
-        reasons: verified.shareSafety.reasons.map((reason) => reason.code)
-    };
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "observer-data.json"), `${JSON.stringify(observerData, null, 2)}\n`, "utf8");
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "study-analysis.json"), `${JSON.stringify(analysis, null, 2)}\n`, "utf8");
-    await writeContainedOutputFile(preparedRunPaths, path.join("observer", "index.html"), renderObserverHtml(observerData, { analysis }), "utf8");
-    await validatePreparedRunArtifactPaths(preparedRunPaths);
-    const relativeObserverPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "index.html");
-    const relativeObserverDataPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "observer-data.json");
-    const relativeEventsPath = path.join(preparedRunPaths.relativeRunRoot, "events.ndjson");
-    const observerUrl = pathToFileURL(observerPath).href;
-    const openResult = options.open === true ? openTarget(observerPath) : { opened: false };
-    const result = {
-        schema: OBSERVER_SCHEMA,
-        ok: true,
-        cwd,
-        run: loaded.bundle.runId,
-        observerPath: relativeObserverPath,
-        observerDataPath: relativeObserverDataPath,
-        eventsPath: relativeEventsPath,
-        observerUrl,
-        bundlePath: loaded.bundlePath,
-        opened: openResult.opened,
-        ...(openResult.command ? { openCommand: openResult.command } : {}),
-        warnings: [
-            loaded.bundle.mode === "live"
-                ? "Observer renders verified local evidence artifacts; runtime stream auth URLs are not persisted."
-                : "Observer renders local contract evidence only; dry-run lanes do not claim product behavior proof.",
-            "Before filing public feedback, use `humanish feedback issue` so redaction and public-safety checks gate the payload.",
-            ...(openResult.warning ? [openResult.warning] : [])
-        ]
-    };
-    observerPreparedRunPaths.set(result, preparedRunPaths);
-    return result;
-}
-function observerRunError(cwd, run, code, message) {
-    return {
-        schema: OBSERVER_SCHEMA,
-        ok: false,
-        cwd,
-        run,
-        warnings: [],
-        error: { code, message }
-    };
-}
-async function resolveObserverRunSelection(cwd, runInput) {
-    const runsRoot = await pinDirectory(path.join(cwd, ".humanish", "runs"));
-    if (runInput !== "latest") {
-        const runRoot = isSafeRunIdSegment(runInput)
-            ? await pinDirectChildDirectory(runsRoot, runInput)
-            : null;
-        return runRoot ? { runId: runInput, runRoot, runsRoot } : null;
-    }
-    const latestBytes = await readContainedFile(runsRoot, path.join(runsRoot.physicalPath, "latest.json"));
-    if (!latestBytes)
-        return null;
-    const pointer = JSON.parse(latestBytes.toString("utf8"));
-    if (typeof pointer.runId !== "string" || typeof pointer.path !== "string" || !isSafeRunIdSegment(pointer.runId)) {
-        return null;
-    }
-    const declared = resolveLatestRunDirectory(cwd, { path: pointer.path, runId: pointer.runId });
-    if (!declared)
-        return null;
-    const expected = path.join(runsRoot.physicalPath, pointer.runId);
-    const runRoot = await pinDirectChildDirectory(runsRoot, pointer.runId);
-    if (!runRoot || runRoot.physicalPath !== expected)
-        return null;
-    return { runId: pointer.runId, runRoot, runsRoot };
-}
-export async function serveObserver(result, options = {}) {
-    if (!result.ok || !result.observerPath) {
-        throw new Error("Cannot serve an observer result that did not render successfully.");
-    }
-    const cwd = path.resolve(result.cwd);
-    const retainedRunPaths = observerPreparedRunPaths.get(result);
-    const preparedRunPaths = retainedRunPaths
-        ? await validatePreparedRunArtifactPaths(retainedRunPaths)
-        : await bindExistingRunArtifactPaths(cwd, result.run);
-    const runRoot = await pinDirectory(preparedRunPaths.physicalRunRoot);
-    const proofRoot = await pinDirectory(preparedRunPaths.physicalRunsRoot);
-    const expectedRelativeObserverPath = path.join(preparedRunPaths.relativeRunRoot, "observer", "index.html");
-    if (result.observerPath !== expectedRelativeObserverPath) {
-        throw new Error("Observer path does not match the selected run.");
-    }
-    // The live server renders observer/index.html from the pinned run bundle on
-    // each request, so an attached in-progress Observer legitimately has no
-    // static index file yet. The exact lexical result path was checked above;
-    // keep serving from the identity-bound physical run root.
-    const observerPath = path.join(preparedRunPaths.physicalRunRoot, "observer", "index.html");
-    if (observerPath !== path.join(runRoot.physicalPath, "observer", "index.html")) {
-        throw new Error("Observer path does not match the selected run.");
-    }
-    const runtimeStreamUrls = () => observerRuntimeStreamUrls.get(result) ?? [];
-    const exposed = options.exposed === true;
-    const scopedToRun = exposed || options.scope === "run";
-    // Host allowlist for exposed mode (DNS-rebinding defense, identical to the run-library surface).
-    // Seeded with the loopback names after bind; addPublicOrigin extends it with the tunnel/public-url
-    // host. Never consulted in loopback (non-exposed) mode.
-    const hostAllowlist = new Set();
-    const server = createServer(async (request, response) => {
-        try {
-            // Every response, including run HTML artifacts, must refuse framing. A provider iframe
-            // with its own origin intact must not navigate back here and gain the Observer's origin.
-            for (const [name, value] of Object.entries(buildServeSecurityHeaders())) {
-                response.setHeader(name, value);
-            }
-            if (exposed) {
-                if (!hostAllowed(request.headers.host, hostAllowlist)) {
-                    writeResponse(response, 421, "Misdirected Request", "text/plain; charset=utf-8");
-                    return;
-                }
-            }
-            const url = new URL(request.url ?? "/", `http://${request.headers.host ?? "127.0.0.1"}`);
-            if (url.pathname === "/") {
-                response.writeHead(302, { location: "/observer/index.html" });
-                response.end();
-                return;
-            }
-            if (url.pathname === "/_humanish/history.json") {
-                const history = await buildHistoryIndex(proofRoot);
-                // Exposed watch and selected-run viewers cannot enumerate other runs. Full-library
-                // loopback viewers retain the complete project index.
-                if (scopedToRun) {
-                    const attachedRuns = history.runs.filter((entry) => entry.runId === result.run);
-                    writeResponse(response, 200, JSON.stringify({ latestRunId: attachedRuns.length > 0 ? result.run : null, runs: attachedRuns }, null, 2), "application/json; charset=utf-8");
-                    return;
-                }
-                writeResponse(response, 200, JSON.stringify(history, null, 2), "application/json; charset=utf-8");
-                return;
-            }
-            if (url.pathname.startsWith("/_humanish/runs/")) {
-                const runRoute = matchRunRoute(url.pathname);
-                if (!runRoute) {
-                    writeResponse(response, 404, "Run not found", "text/plain; charset=utf-8");
-                    return;
-                }
-                // Scoped viewers cannot distinguish another run from a nonexistent one.
-                if (scopedToRun && runRoute.runId !== result.run) {
-                    writeResponse(response, 404, "Run not found", "text/plain; charset=utf-8");
-                    return;
-                }
-                const targetRoot = await pinDirectChildDirectory(proofRoot, runRoute.runId);
-                if (!targetRoot) {
-                    writeResponse(response, 404, "Run not found", "text/plain; charset=utf-8");
-                    return;
-                }
-                await serveRunPath(targetRoot, runRoute.relativePath || "observer/index.html", response, runRoute.runId === result.run ? runtimeStreamUrls() : [], request);
-                return;
-            }
-            await serveRunPath(runRoot, decodeURIComponent(url.pathname.slice(1)), response, runtimeStreamUrls(), request);
-        }
-        catch {
-            writeResponse(response, 500, "Observer request failed", "text/plain; charset=utf-8");
-        }
-    });
-    const port = await listenOnLoopback(server, options.port ?? 0);
-    if (exposed) {
-        hostAllowlist.add(`127.0.0.1:${port}`);
-        hostAllowlist.add(`localhost:${port}`);
-        hostAllowlist.add(`[::1]:${port}`);
-    }
-    const url = `http://127.0.0.1:${port}/observer/index.html`;
-    const openResult = options.open === true ? openTarget(url) : { opened: false };
-    return {
-        url,
-        port,
-        opened: openResult.opened,
-        ...(openResult.command ? { openCommand: openResult.command } : {}),
-        ...(openResult.warning ? { warning: openResult.warning } : {}),
-        // A tunnel's public origin is only known after it starts (post bind). Declaring it here extends
-        // the Host allowlist so the authenticated edge is admitted; a no-op in loopback mode (the
-        // allowlist is never consulted) and for an unparseable origin.
-        addPublicOrigin(origin) {
-            if (!exposed) {
-                return;
-            }
-            const parsed = parsePublicOrigin(origin);
-            if (parsed) {
-                hostAllowlist.add(parsed.host);
-            }
-        },
-        close: () => closeServer(server)
-    };
-}
-// ---- The Observer (#426): a prebuilt self-contained single-file app (observer/ workspace) ----
-// carrying one JSON slot; rendering a run = injecting its snapshot (observer/scripts/inject.ts
-// is the reference implementation this mirrors). The seam lives here because every surface —
-// observe, watch, serve, and the lab call sites — funnels through renderObserverHtml. The
-// legacy string-concat renderer was deleted at cutover (2026-08-16); rollback is a version pin.
-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 beside this module. Never
-    // auto-built — an installed package either carries it or is broken; reinstall.
-    const packagedHtml = readObserverArtifact(path.join(moduleDir, "observer-app.html"));
-    if (packagedHtml !== null) {
-        cachedObserverArtifact = packagedHtml;
-        return packagedHtml;
-    }
-    // Repo checkout (src/ and dist/ both sit one level under the root): build the
-    // workspace on demand — missing after a fresh pull, stale after edits — so the
-    // flag just works in the dev loop instead of demanding a manual build step.
-    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 ?? {});
-}
-/** Analysis cannot grant filesystem authority or make an otherwise readable recording disappear. */
-async function readObserverAnalysis(runRoot) {
-    try {
-        const runId = path.basename(runRoot.physicalPath);
-        const cwd = path.dirname(path.dirname(path.dirname(runRoot.physicalPath)));
-        const prepared = await bindExistingRunArtifactPaths(cwd, runId);
-        if (prepared.physicalRunRoot !== runRoot.physicalPath
-            || prepared.runRootIdentity.birthtimeNs !== runRoot.birthtimeNs
-            || prepared.runRootIdentity.dev !== runRoot.dev || prepared.runRootIdentity.ino !== runRoot.ino) {
-            throw new Error("ANALYSIS_STORAGE_CHANGED");
-        }
-        return projectShareCheckedAnalysis(await loadStudyAnalysis(prepared));
-    }
-    catch {
-        return { state: "invalid", analysis: null, corrections: [], warnings: ["Analysis could not be validated against this recording."] };
-    }
-}
-/** internal: consumed by observer-serve */
-export async function serveRunPath(runRoot, relativePath, response, runtimeStreamUrls = [], request) {
-    const root = runRoot.physicalPath;
-    const filePath = path.resolve(root, relativePath === "" ? "observer/index.html" : relativePath);
-    if (!isPathInside(root, filePath)) {
-        writeResponse(response, 403, "Forbidden", "text/plain; charset=utf-8");
-        return;
-    }
-    // Alias spellings such as observer//observer-data.json must use the same projection,
-    // not fall through to a raw persisted file and inherit a forged runtime grant.
-    const cleanedRelativePath = path.relative(root, filePath).split(path.sep).join("/");
-    // Derived records have a validated projection endpoint below. Never let generic
-    // file serving bypass its current-content checks or a warmed source-only admission cache.
-    const derivedRoot = cleanedRelativePath.split("/")[0];
-    const derivedLeaf = path.posix.basename(cleanedRelativePath);
-    if (derivedRoot === ".analysis-lock"
-        || derivedLeaf.startsWith(".humanish-write-")
-        || isStudyAnalysisRecordPath(cleanedRelativePath)) {
-        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
-        return;
-    }
-    if (cleanedRelativePath === "observer/index.html") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
-            return;
-        }
-        const analysis = await readObserverAnalysis(runRoot);
-        writeResponse(response, 200, renderObserverHtml(observerData, { analysis }), "text/html; charset=utf-8");
-        return;
-    }
-    if (cleanedRelativePath === "observer/observer-data.json") {
-        const observerData = await readObserverData(runRoot, runtimeStreamUrls);
-        if (!observerData) {
-            writeResponse(response, 404, "Observer data not found", "text/plain; charset=utf-8");
-            return;
-        }
-        writeResponse(response, 200, JSON.stringify(observerData, null, 2), "application/json; charset=utf-8");
-        return;
-    }
-    if (cleanedRelativePath === "observer/study-analysis.json") {
-        writeResponse(response, 200, JSON.stringify(await readObserverAnalysis(runRoot)), "application/json; charset=utf-8");
-        return;
-    }
-    if (path.extname(filePath).toLowerCase() === ".mp4") {
-        await serveContainedMedia(runRoot, filePath, response, request);
-        return;
-    }
-    try {
-        const body = await readContainedFile(runRoot, filePath);
-        if (!body) {
-            writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
-            return;
-        }
-        response.writeHead(200, {
-            ...buildArtifactSecurityHeaders(),
-            "content-type": contentTypeForPath(filePath)
-        });
-        response.end(body);
-    }
-    catch {
-        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
-    }
-}
-async function readObserverData(runRoot, runtimeStreamUrls = []) {
-    // Best-effort load from either source. Both reads swallow all errors on
-    // purpose: this runs on every browser poll of a live run, where run.json may
-    // be absent, still being written (a partial-JSON parse error), or superseded
-    // by observer-data.json. A transient failure just falls through to the next
-    // source, or to null -> a 404 the poller retries; it must not surface a 500.
-    try {
-        const bundleBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "run.json"));
-        if (!bundleBytes)
-            throw new Error("run.json unavailable");
-        const bundle = JSON.parse(bundleBytes.toString("utf8"));
-        return withRuntimeStreamUrls(await withLocalRunStatus(runRoot, buildObserverData(bundle)), runtimeStreamUrls);
-    }
-    catch { }
-    try {
-        const observerBytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, "observer", "observer-data.json"));
-        if (!observerBytes)
-            throw new Error("observer-data.json unavailable");
-        return withRuntimeStreamUrls(await withLocalRunStatus(runRoot, withObserverEndings(JSON.parse(observerBytes.toString("utf8")))), runtimeStreamUrls);
-    }
-    catch { }
-    return null;
-}
-/**
- * Liveness is a current read of a contained local status record, separate from run evidence.
- * A stale heartbeat means unknown: neither an old timestamp nor a persisted PID proves that a
- * process died (the evidence may have been copied from another machine). No PID is served/probed.
- */
-async function withLocalRunStatus(runRoot, input) {
-    // A served observation must never be inherited from a persisted projection or export.
-    const { runtime: _persistedRuntime, ...data } = input;
-    try {
-        const bytes = await readContainedFile(runRoot, path.join(runRoot.physicalPath, RUN_STATUS_FILE));
-        if (!bytes)
-            return data;
-        const record = JSON.parse(bytes.toString("utf8"));
-        if (!isRunStatusRecord(record) || record.runId !== data.run.runId || record.mode !== data.run.mode
-            || record.runId !== path.basename(runRoot.physicalPath))
-            return data;
-        const now = Date.now();
-        const started = Date.parse(record.startedAt);
-        const updated = Date.parse(record.updatedAt);
-        const timestampsValid = Number.isFinite(started) && Number.isFinite(updated)
-            && started <= updated && updated <= now;
-        let state = "unknown";
-        if (timestampsValid) {
-            if (record.state === "finished") {
-                state = "finished";
-            }
-            else if (now - updated <= RUN_STATUS_STALE_MS) {
-                state = "running";
-            }
-        }
-        return { ...data, runtime: { state, observedAt: new Date(now).toISOString(), source: "local-run-status" } };
-    }
-    catch {
-        return data;
-    }
-}
-/** internal: exported for the #357 lifecycle tests (consumed by observer-serve). */
-export function withRuntimeStreamUrls(data, runtimeStreamUrls) {
-    const byStream = new Map(runtimeStreamUrls.map((stream) => [stream.streamId, stream]));
-    return {
-        ...data,
-        streams: data.streams.map((input) => {
-            // JSON projections are untrusted, including fallback observer-data.json. A marker saved in
-            // a bundle is never authority; only this process's attached runtime map grants it again.
-            const stream = input.embed === undefined ? input : { ...input, embed: recordedStreamEmbed(input.embed) };
-            const runtime = byStream.get(stream.id);
-            if (!runtime)
-                return stream;
-            if (runtime.ended)
-                return { ...stream, liveEnded: true };
-            const url = runtimeDesktopUrl(runtime.url);
-            if (!url)
-                return stream;
-            return {
-                ...stream,
-                ...(stream.liveEnded === true ? { liveEnded: false } : {}),
-                embed: {
-                    ...(stream.embed ?? { title: stream.label }),
-                    kind: "iframe",
-                    url,
-                    runtimeDesktop: true
-                },
-                transport: "sse",
-                url
-            };
-        })
-    };
-}
-function runtimeDesktopUrl(value) {
-    if (!value || value.length > 16_384 || /[\u0000-\u0020\u007f\\]/.test(value))
-        return null;
-    try {
-        const url = new URL(value);
-        return (url.protocol === "http:" || url.protocol === "https:") && !url.username && !url.password ? url.href : null;
-    }
-    catch {
-        return null;
-    }
-}
-/** internal: consumed by observer-serve */
-export async function buildHistoryIndex(proofRoot) {
-    await assertPinnedDirectory(proofRoot);
-    const physicalCwd = path.dirname(path.dirname(proofRoot.physicalPath));
-    const listed = await listRuns(physicalCwd);
-    const runs = await Promise.all(listed.runs.slice(0, 80).map(async (run) => {
-        const root = await pinDirectChildDirectory(proofRoot, run.runId);
-        const data = root ? await readObserverData(root) : null;
-        return {
-            runId: run.runId,
-            createdAt: run.createdAt,
-            mode: run.mode,
-            href: `/_humanish/runs/${encodeURIComponent(run.runId)}/observer/index.html`,
-            status: data?.run.status ?? "unknown",
-            ...(data?.runtime ? { runtimeState: data.runtime.state } : {}),
-            streamCount: data?.streams.length ?? 0,
-            // Labeled run-total cost estimate (advisory; null when the run carries no cost summary).
-            estimatedCostUsd: data?.cost?.estimatedTotalUsd ?? null,
-            costRatesAsOf: data?.cost?.ratesAsOf ?? null,
-            costPlaceholder: data?.cost?.placeholder ?? false
-        };
-    }));
-    await assertPinnedDirectory(proofRoot);
-    return {
-        latestRunId: listed.latest && isSafeRunIdSegment(listed.latest) ? listed.latest : null,
-        runs
-    };
-}
-/** internal: consumed by observer-serve */
-export function matchRunRoute(pathname) {
-    const match = pathname.match(/^\/_humanish\/runs\/([^/]+)(?:\/(.*))?$/);
-    if (!match)
-        return null;
-    try {
-        const runId = decodeURIComponent(match[1] ?? "");
-        if (!isSafeRunIdSegment(runId))
-            return null;
-        return {
-            runId,
-            relativePath: decodeURIComponent(match[2] || "observer/index.html")
-        };
-    }
-    catch {
-        return null;
-    }
-}
-async function readContainedFile(root, filePathInput) {
-    const opened = await openContainedFile(root, filePathInput);
-    if (!opened)
-        return null;
-    try {
-        const body = await opened.handle.readFile();
-        await assertPinnedDirectory(root);
-        return body;
-    }
-    catch {
-        return null;
-    }
-    finally {
-        await opened.handle.close();
-    }
-}
-async function openContainedFile(root, filePathInput) {
-    const filePath = path.resolve(filePathInput);
-    if (!isPathInside(root.physicalPath, filePath))
-        return null;
-    let handle = null;
-    try {
-        await assertPinnedDirectory(root);
-        const expectedStats = await inspectContainedRegularFile(root, filePath);
-        if (!expectedStats)
-            return null;
-        handle = await open(filePath, fsConstants.O_RDONLY | fsConstants.O_NOFOLLOW);
-        const openedStats = await handle.stat({ bigint: true });
-        if (!openedStats.isFile() || openedStats.nlink !== 1n || openedStats.dev !== expectedStats.dev || openedStats.ino !== expectedStats.ino) {
-            await handle.close();
-            return null;
-        }
-        const recheckedStats = await inspectContainedRegularFile(root, filePath);
-        if (!recheckedStats || recheckedStats.dev !== expectedStats.dev || recheckedStats.ino !== expectedStats.ino) {
-            await handle.close();
-            return null;
-        }
-        await assertPinnedDirectory(root);
-        return { handle, size: Number(openedStats.size) };
-    }
-    catch {
-        if (handle)
-            await handle.close().catch(() => undefined);
-        return null;
-    }
-}
-function byteRange(value, size) {
-    if (value === undefined)
-        return null;
-    if (Array.isArray(value) || value.includes(","))
-        return "invalid";
-    const match = /^bytes=(\d*)-(\d*)$/.exec(value.trim());
-    if (!match || (!match[1] && !match[2]) || size <= 0)
-        return "invalid";
-    if (!match[1]) {
-        const suffix = Number(match[2]);
-        if (!Number.isSafeInteger(suffix) || suffix <= 0)
-            return "invalid";
-        return { start: Math.max(0, size - suffix), end: size - 1 };
-    }
-    const start = Number(match[1]);
-    const requestedEnd = match[2] ? Number(match[2]) : size - 1;
-    if (!Number.isSafeInteger(start) || !Number.isSafeInteger(requestedEnd) || start < 0 || requestedEnd < start || start >= size)
-        return "invalid";
-    return { start, end: Math.min(requestedEnd, size - 1) };
-}
-async function serveContainedMedia(root, filePath, response, request) {
-    const opened = await openContainedFile(root, filePath);
-    if (!opened) {
-        writeResponse(response, 404, "Not found", "text/plain; charset=utf-8");
-        return;
-    }
-    const range = byteRange(request?.headers.range, opened.size);
-    if (range === "invalid") {
-        await opened.handle.close();
-        response.writeHead(416, { ...buildArtifactSecurityHeaders(), "accept-ranges": "bytes", "content-range": `bytes */${opened.size}`, "content-length": "0" });
-        response.end();
-        return;
-    }
-    const start = range?.start ?? 0;
-    const end = range?.end ?? Math.max(0, opened.size - 1);
-    const status = range ? 206 : 200;
-    response.writeHead(status, {
-        ...buildArtifactSecurityHeaders(),
-        "accept-ranges": "bytes",
-        "content-type": "video/mp4",
-        "content-length": String(opened.size === 0 ? 0 : end - start + 1),
-        ...(range ? { "content-range": `bytes ${start}-${end}/${opened.size}` } : {})
-    });
-    if (request?.method === "HEAD" || opened.size === 0) {
-        await opened.handle.close();
-        response.end();
-        return;
-    }
-    let stream;
-    try {
-        stream = opened.handle.createReadStream({ start, end, autoClose: false });
-        await new Promise((resolve, reject) => {
-            stream.once("error", reject);
-            response.once("finish", resolve);
-            response.once("close", resolve);
-            stream.pipe(response);
-        });
-    }
-    catch {
-        // Headers already describe a fixed byte interval. A late disk/read failure
-        // cannot become a second HTTP response; terminate the incomplete body.
-        response.destroy();
-    }
-    finally {
-        stream?.destroy();
-        await opened.handle.close().catch(() => undefined);
-    }
-}
-async function inspectContainedRegularFile(root, filePath) {
-    const relative = path.relative(root.physicalPath, filePath);
-    if (!relative || relative === ".." || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
-        return null;
-    }
-    const segments = relative.split(path.sep).filter(Boolean);
-    let current = root.physicalPath;
-    let fileIdentity = null;
-    for (const [index, segment] of segments.entries()) {
-        current = path.join(current, segment);
-        const stats = await lstat(current, { bigint: true });
-        if (stats.isSymbolicLink())
-            return null;
-        if (index < segments.length - 1) {
-            if (!stats.isDirectory())
-                return null;
-        }
-        else {
-            if (!stats.isFile() || stats.nlink !== 1n)
-                return null;
-            fileIdentity = { dev: stats.dev, ino: stats.ino };
-        }
-    }
-    if (await realpath(filePath) !== filePath)
-        return null;
-    return fileIdentity;
-}
-/** internal: consumed by observer-serve */
-export async function pinDirectory(directoryInput) {
-    const physicalPath = await realpath(path.resolve(directoryInput));
-    const stats = await lstat(physicalPath, { bigint: true });
-    if (stats.isSymbolicLink() || !stats.isDirectory()) {
-        throw new Error("Observer roots must be physical directories.");
-    }
-    return Object.freeze({ birthtimeNs: stats.birthtimeNs, dev: stats.dev, ino: stats.ino, physicalPath });
-}
-/** internal: consumed by observer-serve */
-export async function pinDirectChildDirectory(root, name) {
-    if (!isSafeRunIdSegment(name))
-        return null;
-    try {
-        await assertPinnedDirectory(root);
-        const candidate = path.join(root.physicalPath, name);
-        const pinned = await pinDirectory(candidate);
-        if (pinned.physicalPath !== candidate || path.dirname(pinned.physicalPath) !== root.physicalPath) {
-            return null;
-        }
-        await assertPinnedDirectory(root);
-        return pinned;
-    }
-    catch {
-        return null;
-    }
-}
-async function assertPinnedDirectory(root) {
-    const stats = await lstat(root.physicalPath, { bigint: true });
-    if (stats.isSymbolicLink()
-        || !stats.isDirectory()
-        || stats.birthtimeNs !== root.birthtimeNs
-        || stats.dev !== root.dev
-        || stats.ino !== root.ino
-        || await realpath(root.physicalPath) !== root.physicalPath) {
-        throw new Error("Observer root identity changed.");
-    }
-}
-function writeResponse(response, status, body, contentType) {
-    response.writeHead(status, {
-        "cache-control": "no-store",
-        "content-type": contentType
-    });
-    response.end(body);
-}
-function contentTypeForPath(filePath) {
-    switch (path.extname(filePath)) {
-        case ".html":
-            return "text/html; charset=utf-8";
-        case ".json":
-            return "application/json; charset=utf-8";
-        case ".md":
-            return "text/markdown; charset=utf-8";
-        case ".ndjson":
-            return "application/x-ndjson; charset=utf-8";
-        case ".png":
-            return "image/png";
-        case ".jpg":
-        case ".jpeg":
-            return "image/jpeg";
-        case ".webp":
-            return "image/webp";
-        default:
-            return "text/plain; charset=utf-8";
-    }
-}
-export function openTarget(target) {
-    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
-    const args = process.platform === "win32" ? ["/c", "start", "", target] : [target];
-    try {
-        const child = spawn(command, args, {
-            detached: true,
-            stdio: "ignore"
-        });
-        // Missing desktop openers fail asynchronously (ENOENT), especially over SSH or in a
-        // minimal container. The served URL remains usable; an opener must never crash its server.
-        child.on("error", () => { });
-        child.unref();
-        return { opened: true, command: [command, ...args].join(" ") };
-    }
-    catch (error) {
-        return {
-            opened: false,
-            command: [command, ...args].join(" "),
-            warning: `Could not open observer automatically: ${error instanceof Error ? error.message : String(error)}`
-        };
-    }
-}
-function closeServer(server) {
-    return new Promise((resolve, reject) => {
-        server.close((error) => {
-            if (error) {
-                reject(error);
-            }
-            else {
-                resolve();
-            }
-        });
-    });
-}
-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");
-}
-//# sourceMappingURL=observer.js.map