humanish 0.104.3 → 0.106.0

package/dist/lab/adapter-extension.js

@@ -0,0 +1,253 @@
+import path from "node:path";
+import { isFeedbackIdempotencyKey } from "../run/feedback-shape.js";
+/** A DECLARED scorer that returned a malformed value never rendered a verdict. */
+export const DECLARED_SCORER_MALFORMED = "Declared product scorer returned a malformed value instead of a verdict; a declared gate that cannot render a pass is recorded as a fail, never a silent pass.";
+/** A DECLARED scorer that threw never rendered a verdict. `detail` is already sanitized. */
+export function declaredScorerThrew(detail) {
+    return `Declared product scorer threw before returning a verdict (${detail}); a crashed declared gate is recorded as a fail, never a silent pass.`;
+}
+export async function applyBrowserAdapterHooks(args) {
+    const { hooks, context, bundle, sanitize, warnings, hookLabel, scorerProvenance } = args;
+    if (!hooks?.score && !hooks?.deriveFeedback && !hooks?.deriveArtifacts)
+        return { failures: [] };
+    const declared = scorerProvenance !== undefined;
+    // Record the loaded scorer's identity regardless of hook outcome (a throwing/invalid scorer was
+    // still loaded and attempted). A VALID status:"fail" is a failure (library + declared, the
+    // pre-#316 (#165) path); a DECLARED scorer that THROWS or returns MALFORMED is one too (below).
+    if (scorerProvenance)
+        bundle.scorerProvenance = scorerProvenance;
+    // The scorer sees a READ-ONLY view of the bundle: it cannot mutate noSpend/cost/review in place to
+    // launder a verdict (a tamper attempt throws in the scorer's strict-mode ESM and is caught below as
+    // a hook failure). The seam still stamps the REAL bundle.
+    const scoringContext = {
+        ...context,
+        bundle: frozenBundleView(context.bundle),
+    };
+    const scrubValue = (value) => {
+        const encoded = JSON.stringify(value);
+        return encoded === undefined ? value : JSON.parse(sanitize(encoded));
+    };
+    const failures = [];
+    if (hooks.score) {
+        try {
+            const score = await hooks.score(scoringContext);
+            const cleaned = scrubValue(score);
+            if (isAdapterScoreShape(cleaned)) {
+                bundle.adapterScore = cleaned;
+                const message = adapterScoreFailureMessage(bundle);
+                if (message !== undefined)
+                    failures.push(message);
+            }
+            else {
+                warnings.push(`${hookLabel}.score returned a value that is not a well-formed humanish.adapter-score.v1 (non-empty namespace + status + numeric score + summary); dropped so the bundle stays verifiable.`);
+                if (declared)
+                    failures.push(DECLARED_SCORER_MALFORMED);
+            }
+        }
+        catch (error) {
+            const detail = sanitize(error instanceof Error ? error.message : String(error));
+            warnings.push(`${hookLabel}.score threw (${detail}); dropped so the bundle stays verifiable.`);
+            if (declared)
+                failures.push(declaredScorerThrew(detail));
+        }
+    }
+    if (hooks.deriveFeedback) {
+        try {
+            const candidates = await hooks.deriveFeedback(scoringContext);
+            const accepted = [];
+            for (const candidate of Array.isArray(candidates) ? candidates : []) {
+                const cleaned = scrubValue(candidate);
+                if (isAdapterFeedbackCandidateShape(cleaned))
+                    accepted.push(cleaned);
+                else
+                    warnings.push(`${hookLabel}.deriveFeedback returned a candidate that is not a well-formed humanish.feedback-candidate.v1 (or its adapter block lacked a non-empty namespace + data record); dropped so the bundle stays verifiable.`);
+            }
+            if (accepted.length > 0) {
+                bundle.feedbackCandidates = [...bundle.feedbackCandidates, ...accepted];
+            }
+        }
+        catch (error) {
+            warnings.push(`${hookLabel}.deriveFeedback threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+        }
+    }
+    if (hooks.deriveArtifacts) {
+        try {
+            const artifacts = await hooks.deriveArtifacts(scoringContext);
+            const accepted = [];
+            for (const artifact of Array.isArray(artifacts) ? artifacts : []) {
+                const cleaned = scrubValue(artifact);
+                if (isAdapterArtifactShape(cleaned))
+                    accepted.push(cleaned);
+                else
+                    warnings.push(`${hookLabel}.deriveArtifacts returned an artifact that is not a well-formed humanish.adapter-artifact.v1 (non-empty namespace + label + local path + supported kind); dropped so the bundle stays verifiable.`);
+            }
+            if (accepted.length > 0) {
+                bundle.adapterArtifacts = [...(bundle.adapterArtifacts ?? []), ...accepted];
+            }
+        }
+        catch (error) {
+            warnings.push(`${hookLabel}.deriveArtifacts threw (${sanitize(error instanceof Error ? error.message : String(error))}); dropped so the bundle stays verifiable.`);
+        }
+    }
+    return { failures };
+}
+export function adapterScoreFailureMessage(bundle) {
+    return bundle.adapterScore?.status === "fail"
+        ? `Adapter scorer failed the run: ${bundle.adapterScore.summary}`
+        : undefined;
+}
+/**
+ * Deep-freeze a structured clone so a loaded scorer sees a READ-ONLY bundle: it cannot mutate
+ * noSpend/cost/review in place to launder a verdict (which would defeat the costProbe-not-loadable
+ * guarantee). A tamper attempt throws in the scorer's strict-mode ESM and is caught as a hook failure.
+ * Legitimate read-only scoring is unaffected. The seam always stamps the REAL bundle, never this view.
+ */
+export function frozenBundleView(bundle) {
+    const clone = structuredClone(bundle);
+    const freeze = (obj) => {
+        if (obj !== null && typeof obj === "object" && !Object.isFrozen(obj)) {
+            Object.freeze(obj);
+            for (const key of Object.keys(obj)) {
+                freeze(obj[key]);
+            }
+        }
+    };
+    freeze(clone);
+    return clone;
+}
+function isAdapterScoreShape(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        !Array.isArray(value) &&
+        value.schema === "humanish.adapter-score.v1" &&
+        typeof value.namespace === "string" &&
+        value.namespace.trim().length > 0 &&
+        ["pass", "partial", "fail"].includes(value.status) &&
+        typeof value.score === "number" &&
+        Number.isFinite(value.score) &&
+        typeof value.summary === "string" &&
+        (value.data === undefined ||
+            (typeof value.data === "object" &&
+                value.data !== null &&
+                !Array.isArray(value.data))));
+}
+function isAdapterFeedbackCandidateShape(value) {
+    if (!isRecord(value))
+        return false;
+    const candidate = value;
+    if (candidate.schema !== "humanish.feedback-candidate.v1" ||
+        typeof candidate.id !== "string" ||
+        typeof candidate.run_id !== "string" ||
+        (candidate.stream_id !== undefined && typeof candidate.stream_id !== "string") ||
+        typeof candidate.adapter_id !== "string" ||
+        typeof candidate.scenario_id !== "string" ||
+        typeof candidate.persona_id !== "string" ||
+        !isFeedbackActor(candidate.actor) ||
+        !isFeedbackSubstrate(candidate.substrate) ||
+        !isFeedbackFailureOwner(candidate.failure_owner) ||
+        typeof candidate.summary !== "string" ||
+        candidate.summary.trim().length === 0 ||
+        typeof candidate.expected !== "string" ||
+        typeof candidate.actual !== "string" ||
+        !Array.isArray(candidate.evidence) ||
+        !candidate.evidence.every(isFeedbackEvidence) ||
+        !isRecord(candidate.redaction) ||
+        candidate.redaction.status !== "passed" ||
+        typeof candidate.redaction.notes !== "string" ||
+        !isFeedbackIdempotencyKey(candidate.idempotency_key) ||
+        !isFeedbackNextState(candidate.proposed_next_state) ||
+        !Array.isArray(candidate.acceptance_proof) ||
+        !candidate.acceptance_proof.every((item) => typeof item === "string")) {
+        return false;
+    }
+    if (candidate.adapter !== undefined) {
+        const adapter = candidate.adapter;
+        if (!isRecord(adapter) ||
+            typeof adapter.namespace !== "string" ||
+            adapter.namespace.trim().length === 0 ||
+            !isRecord(adapter.data)) {
+            return false;
+        }
+    }
+    return true;
+}
+function isAdapterArtifactShape(value) {
+    if (!isRecord(value))
+        return false;
+    const artifact = value;
+    return (artifact.schema === "humanish.adapter-artifact.v1" &&
+        typeof artifact.namespace === "string" &&
+        artifact.namespace.trim().length > 0 &&
+        typeof artifact.label === "string" &&
+        artifact.label.trim().length > 0 &&
+        typeof artifact.path === "string" &&
+        isSafeRelativeArtifactPath(artifact.path) &&
+        isAdapterArtifactKind(artifact.kind) &&
+        typeof artifact.note === "string" &&
+        artifact.note.trim().length > 0);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSafeRelativeArtifactPath(value) {
+    return (value.trim().length > 0 &&
+        !path.isAbsolute(value) &&
+        !value.includes("://") &&
+        !value.split(/[\\/]/).some((part) => part === ".." || part === "." || part.length === 0));
+}
+function isAdapterArtifactKind(value) {
+    return (value === "state" ||
+        value === "review" ||
+        value === "log" ||
+        value === "trace" ||
+        value === "screenshot" ||
+        value === "filesystem" ||
+        value === "summary");
+}
+function isFeedbackActor(value) {
+    return (value === "codex-tui" ||
+        value === "codex-exec" ||
+        value === "codex-app-server" ||
+        value === "computer-use" ||
+        value === "synthetic-dry-run" ||
+        value === "unknown");
+}
+function isFeedbackSubstrate(value) {
+    return (value === "e2b-desktop" ||
+        value === "local-desktop" ||
+        value === "e2b-terminal" ||
+        value === "local-filesystem" ||
+        value === "codex-app-server" ||
+        value === "unknown");
+}
+function isFeedbackFailureOwner(value) {
+    return (value === "harness" ||
+        value === "target-app" ||
+        value === "actor" ||
+        value === "environment" ||
+        value === "unknown");
+}
+function isFeedbackNextState(value) {
+    return (value === "watch" ||
+        value === "adapter-hardening" ||
+        value === "target-app-setup" ||
+        value === "actor-auth" ||
+        value === "setup-quality-review" ||
+        value === "study-quality-review");
+}
+function isFeedbackEvidence(value) {
+    if (!isRecord(value))
+        return false;
+    return (typeof value.path === "string" &&
+        value.path.length > 0 &&
+        !path.isAbsolute(value.path) &&
+        !value.path.includes("://") &&
+        !value.path.includes("..") &&
+        (value.kind === "review" ||
+            value.kind === "state" ||
+            value.kind === "log" ||
+            value.kind === "trace" ||
+            value.kind === "screenshot" ||
+            value.kind === "filesystem") &&
+        typeof value.note === "string");
+}

package/dist/lab/adapter-scorer-loader.d.ts

@@ -0,0 +1,43 @@
+import type { BrowserLabScoringContext } from "./adapter-extension.js";
+import type { TerminalProductScoringContext } from "../routes/terminal/types.js";
+import type { LabRoute } from "./plan.js";
+import type { RunAdapterArtifact, RunAdapterScore, RunFeedbackCandidate, RunScorerProvenance } from "../run/bundle.js";
+/** The read-model context a loaded scorer sees — the terminal or browser scoring context. The module
+ *  narrows it at runtime (`"product" in ctx` ⇒ terminal; `"backend" in ctx` ⇒ browser). */
+export type AdapterScoringContext = TerminalProductScoringContext | BrowserLabScoringContext;
+/**
+ * The adopter-facing scorer module contract (#316). Export any subset of these from a `.mjs` (or a
+ * `.js`/`.cjs` whose package.json type matches) — named exports OR a single default object. The
+ * loader wires ONLY these three; an exported `executor`/`env`/`provisionSubject`/`costProbe` is never
+ * picked up (the whitelist is the scope guard). A module exporting NONE of them is a hard load error.
+ */
+export interface AdapterScorerModule {
+    score?: (ctx: AdapterScoringContext) => RunAdapterScore | Promise<RunAdapterScore>;
+    deriveFeedback?: (ctx: AdapterScoringContext) => RunFeedbackCandidate[] | Promise<RunFeedbackCandidate[]>;
+    /** Browser-route only; inert on the terminal route (TerminalProductLabHooks carries no artifacts seam). */
+    deriveArtifacts?: (ctx: BrowserLabScoringContext) => RunAdapterArtifact[] | Promise<RunAdapterArtifact[]>;
+}
+type AdapterScorerLoadErrorCode = "HUMANISH_LAB_SCORER_BAD_REF" | "HUMANISH_LAB_SCORER_NOT_FOUND" | "HUMANISH_LAB_SCORER_LOAD_FAILED" | "HUMANISH_LAB_SCORER_NO_HOOKS" | "HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND";
+export type AdapterScorerLoadResult = {
+    ok: true;
+    hooks: AdapterScorerModule;
+    provenance: RunScorerProvenance;
+} | {
+    ok: false;
+    error: {
+        code: AdapterScorerLoadErrorCode;
+        message: string;
+    };
+};
+/**
+ * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
+ * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ */
+export declare function loadAdapterScorer(args: {
+    cwd: string;
+    ref: string;
+    route: LabRoute;
+    source: "manifest" | "cli-flag";
+}): Promise<AdapterScorerLoadResult>;
+export {};

package/dist/lab/adapter-scorer-loader.js

@@ -0,0 +1,130 @@
+// #316 — CLI-loadable adopter scorer. Resolve `review.scorer.ref` / `--scorer` to an out-of-tree
+// scorer module, load it fail-closed (typed error + exit 2, PRE-SPEND), and pick off ONLY the
+// whitelisted read-model hooks {score, deriveFeedback, deriveArtifacts}. `costProbe` is deliberately
+// NOT loadable — an injected provider cost line overwrites the core-measured one and can forge a
+// satisfied no-spend proof, so it stays library-only.
+//
+// TRUST MODEL (stated plainly, no overclaims): the party who writes `review.scorer.ref` is the party
+// who runs `humanish lab run` in their own checkout — identical trust to humanish.lab.yml or a
+// package.json script. #316 adds ZERO new execution capability; it relocates WHERE the reference is
+// declared. Containment is ENTRY-FILE-ONLY: `readContainedRegularFile` blocks abs/`..`/symlink/
+// hardlink/realpath-escape/TOCTOU on the entry module, but `import()` then executes the transitive
+// graph + npm deps with no clamp, and `import()` runs top-level module code before any whitelist
+// check. The whitelist bounds the WIRED HOOK SURFACE, not arbitrary import-time code; the
+// trusted-in-process boundary is the actual safety carrier. The seam's output re-scrub is a
+// best-effort denylist, NOT containment. `review.scorer.ref` entries are executable code — review a
+// PR that adds one as code, not config.
+import { realpath } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { digestText, redactText } from "../evidence/redaction.js";
+import { prepareSelectedOutputDirectory, readContainedRegularFile, } from "../run/contained-output.js";
+/** The routes whose hooks bag can carry the loaded scorer. A declared scorer on ANY other route
+ *  (scripted or preview) aborts at load — a gate that cannot run must never green-pass. */
+const SCORER_CAPABLE_ROUTES = new Set([
+    "terminal",
+    "computer-use",
+    "shared-world",
+]);
+/** `.mjs` is required-canonical; `.js`/`.cjs` accepted but the module system is the adopter repo's
+ *  package.json `type`. `.ts` is rejected — the compiled `dist/` CLI ships no TypeScript loader. */
+const SCORER_EXTENSIONS = new Set([".mjs", ".js", ".cjs"]);
+/**
+ * Resolve + load a config-declared scorer module. Resolution clones scenario.ref exactly
+ * (prepareSelectedOutputDirectory → cwd-clamp → readContainedRegularFile), then `import()`s the
+ * entry file in a BROAD try/catch. The digest is over the readContainedRegularFile ENTRY bytes.
+ */
+export async function loadAdapterScorer(args) {
+    const { route, source } = args;
+    const fail = (code, message) => ({
+        ok: false,
+        error: { code, message },
+    });
+    // A declared gate that cannot run on this route must ABORT (never silently green-pass).
+    if (!SCORER_CAPABLE_ROUTES.has(route)) {
+        return fail("HUMANISH_LAB_SCORER_UNSUPPORTED_BACKEND", `review.scorer.ref is declared but this lab resolves to the ${route} route, which has no adopter-scorer seam. A declared scorer that cannot run must fail closed rather than pass silently — declare it on a terminal, computer-use or shared-world lab.`);
+    }
+    const trimmed = args.ref.trim();
+    if (!trimmed) {
+        return fail("HUMANISH_LAB_SCORER_BAD_REF", "review.scorer.ref must be a non-empty repo-relative path ending in .mjs (recommended), .js, or .cjs.");
+    }
+    // Provenance is recorded repo-relative — an absolute ref (even one that happens to land inside cwd)
+    // is rejected up front rather than silently rewritten to its in-tree relative form.
+    if (path.isAbsolute(trimmed)) {
+        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative path, not absolute — provenance is recorded repo-relative.`);
+    }
+    const ext = path.extname(trimmed).toLowerCase();
+    if (ext === ".ts") {
+        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" ends in .ts, but the shipped CLI runs compiled JS with no TypeScript loader. Precompile to .mjs (recommended) or .js/.cjs.`);
+    }
+    if (!SCORER_EXTENSIONS.has(ext)) {
+        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must be a repo-relative PATH ending in .mjs (recommended), .js, or .cjs — an id-style ref is not supported.`);
+    }
+    // Root token: realpath(cwd) → prepareSelectedOutputDirectory(dirname, cwd). Mirrors scenario.ref.
+    const physicalCwd = await realpath(path.resolve(args.cwd));
+    const root = await prepareSelectedOutputDirectory(path.dirname(physicalCwd), physicalCwd);
+    // Clamp verbatim from the scripted scenario.ref branch: resolve → relative → reject escape/absolute.
+    const absolutePath = path.resolve(root.physicalPath, trimmed);
+    const relative = path.relative(root.physicalPath, absolutePath);
+    if (!relative || relative.startsWith("..") || path.isAbsolute(relative)) {
+        return fail("HUMANISH_LAB_SCORER_BAD_REF", `review.scorer.ref "${trimmed}" must stay inside the target cwd — provenance is recorded repo-relative and an escaping/absolute path (a cwd parent, node_modules above cwd, an absolute path) cannot be.`);
+    }
+    const relPosix = relative.split(path.sep).join("/");
+    // Fail-closed containment gate on the ENTRY file only: rejects symlink, nlink>1, realpath-escape,
+    // TOCTOU. Its returned bytes are the digest input.
+    const bytes = await readContainedRegularFile(root, relPosix);
+    if (!bytes) {
+        return fail("HUMANISH_LAB_SCORER_NOT_FOUND", `review.scorer.ref "${trimmed}" could not be read as a contained regular file (${relPosix}). A scorer must be a regular file inside the target cwd — no symlink, no hardlink, no realpath escape.`);
+    }
+    const digest = digestText(bytes.toString("utf8"));
+    // Import the entry module in a BROAD try/catch (ERR_MODULE_NOT_FOUND / SyntaxError / ERR_REQUIRE_ESM
+    // / top-level throw). import() executes the transitive graph — the cwd clamp guards only the ENTRY
+    // file; out-of-tree/transitive code is acceptable only because of the trust boundary above.
+    let mod;
+    try {
+        const url = pathToFileURL(path.join(root.physicalPath, relPosix)).href;
+        mod = (await import(url));
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const hint = /ERR_REQUIRE_ESM|import statement outside a module|Cannot use import statement|Unexpected (?:token|identifier)|SyntaxError/i.test(detail)
+            ? ' Use a .mjs entry file, or set "type": "module" in the nearest package.json.'
+            : "";
+        return fail("HUMANISH_LAB_SCORER_LOAD_FAILED", `review.scorer.ref "${trimmed}" failed to load: ${redactText(detail)}.${hint}`);
+    }
+    // mod.default ?? mod, then pick off ONLY the whitelist. An exported executor/env/costProbe is never
+    // wired — the whitelist is the scope guard. `exports` records the hooks ACTUALLY WIRED for this
+    // backend: deriveArtifacts is browser-only, so on the terminal route it is neither wired nor
+    // recorded (a scorer that exported ONLY deriveArtifacts there wires nothing and fails closed below,
+    // never a silent no-op).
+    const picked = (mod.default ?? mod);
+    const terminalRoute = route === "terminal";
+    const hooks = {};
+    const exports = [];
+    if (typeof picked.score === "function") {
+        hooks.score = picked.score;
+        exports.push("score");
+    }
+    if (typeof picked.deriveFeedback === "function") {
+        hooks.deriveFeedback = picked.deriveFeedback;
+        exports.push("deriveFeedback");
+    }
+    if (!terminalRoute && typeof picked.deriveArtifacts === "function") {
+        hooks.deriveArtifacts = picked.deriveArtifacts;
+        exports.push("deriveArtifacts");
+    }
+    if (exports.length === 0) {
+        const artifactsOnly = terminalRoute && typeof picked.deriveArtifacts === "function";
+        return fail("HUMANISH_LAB_SCORER_NO_HOOKS", artifactsOnly
+            ? `review.scorer.ref "${trimmed}" exported only deriveArtifacts, which is browser-only and inert on the terminal route. Export score and/or deriveFeedback for a terminal-product scorer.`
+            : `review.scorer.ref "${trimmed}" loaded but exported none of the adopter-scorer hooks (score, deriveFeedback, deriveArtifacts). Export at least one (named, or on a single default object). costProbe is intentionally NOT loadable.`);
+    }
+    const provenance = {
+        schema: "humanish.scorer-provenance.v1",
+        ref: relPosix,
+        digest,
+        source,
+        exports,
+    };
+    return { ok: true, hooks, provenance };
+}

package/dist/lab/bag-overrides.d.ts

@@ -0,0 +1,18 @@
+/** The members each bag type declares, forwarded even when the bag does not enumerate them. */
+export declare const HOOK_MEMBERS: {
+    readonly cua: string[];
+    readonly sharedWorld: string[];
+    readonly terminal: string[];
+    readonly scripted: string[];
+    readonly analysis: string[];
+};
+/**
+ * The bag with `overrides` in place of its own members. Every other member becomes an enumerable
+ * accessor that reads the bag when it is read, so a getter runs only then and a spread of the
+ * result keeps every member. The members are the bag's own and inherited keys (string or symbol)
+ * plus `declared`, the members its type declares, which a proxy-backed bag may answer without
+ * listing. A function is bound to the bag, so its private fields still work. The overrides are
+ * ordinary data properties. Declared members always appear as own properties (undefined when
+ * unset), so code reading a wrapped bag tests the value, never `in`.
+ */
+export declare function withHookOverrides<T extends object>(bag: T | undefined, declared: readonly string[], overrides: Partial<T>): T;

package/dist/lab/bag-overrides.js

@@ -0,0 +1,121 @@
+// A caller's hook bag with some members replaced, without copying the bag's values. Spreading a
+// class instance keeps only its own properties, so a route that spreads a caller's bag loses the
+// class's methods; this builds a plain object that keeps them.
+// Every member each bag type declares. The record type makes the compiler reject a missing or
+// unknown name, so a member added to a bag type must be added here too.
+const cuaMembers = {
+    prepareDesktop: true,
+    onPreflight: true,
+    onPhase: true,
+    onRuntimeStreamReady: true,
+    onRuntimeStreamEnded: true,
+    loadDesktopModule: true,
+    runSession: true,
+    buildExecutor: true,
+    buildProvider: true,
+    createDesktopLane: true,
+    env: true,
+    renderObserverFn: true,
+    now: true,
+    detachedTimers: true,
+    packLocalTree: true,
+    score: true,
+    deriveFeedback: true,
+    deriveArtifacts: true,
+};
+const sharedWorldMembers = {
+    loadDesktopModule: true,
+    prepareDesktop: true,
+    onRuntimeStreamReady: true,
+    onRuntimeStreamEnded: true,
+    runSession: true,
+    env: true,
+    renderObserverFn: true,
+    detachedTimers: true,
+    onPhase: true,
+    now: true,
+    proberCadenceMs: true,
+    handoffDeadlineMs: true,
+    readLobbyCodeFromFrame: true,
+    packLocalTree: true,
+    score: true,
+    deriveFeedback: true,
+    deriveArtifacts: true,
+};
+const terminalMembers = {
+    loadModule: true,
+    env: true,
+    renderObserverFn: true,
+    now: true,
+    costProbe: true,
+    score: true,
+    deriveFeedback: true,
+};
+const scriptedMembers = {
+    runSession: true,
+    launchBrowser: true,
+    env: true,
+    loadDesktopModule: true,
+    prepareDesktop: true,
+    detachedTimers: true,
+    browserCommand: true,
+    renderObserverFn: true,
+    now: true,
+};
+const analysisMembers = {
+    deps: true,
+    onStart: true,
+    run: true,
+};
+/** The members each bag type declares, forwarded even when the bag does not enumerate them. */
+export const HOOK_MEMBERS = {
+    cua: Object.keys(cuaMembers),
+    sharedWorld: Object.keys(sharedWorldMembers),
+    terminal: Object.keys(terminalMembers),
+    scripted: Object.keys(scriptedMembers),
+    analysis: Object.keys(analysisMembers),
+};
+/**
+ * The bag with `overrides` in place of its own members. Every other member becomes an enumerable
+ * accessor that reads the bag when it is read, so a getter runs only then and a spread of the
+ * result keeps every member. The members are the bag's own and inherited keys (string or symbol)
+ * plus `declared`, the members its type declares, which a proxy-backed bag may answer without
+ * listing. A function is bound to the bag, so its private fields still work. The overrides are
+ * ordinary data properties. Declared members always appear as own properties (undefined when
+ * unset), so code reading a wrapped bag tests the value, never `in`.
+ */
+export function withHookOverrides(bag, declared, overrides) {
+    const forward = {};
+    const replaced = new Set(Reflect.ownKeys(overrides));
+    const forwardMember = (key) => {
+        if (key === "constructor" || replaced.has(key) || Object.hasOwn(forward, key))
+            return;
+        Object.defineProperty(forward, key, {
+            enumerable: true,
+            configurable: true,
+            get() {
+                const value = Reflect.get(bag, key, bag);
+                return typeof value === "function" ? value.bind(bag) : value;
+            },
+            set(value) {
+                Reflect.set(bag, key, value, bag);
+            },
+        });
+    };
+    if (bag !== undefined) {
+        for (let source = bag; source !== null && source !== Object.prototype; source = Object.getPrototypeOf(source))
+            for (const key of Reflect.ownKeys(source))
+                forwardMember(key);
+        for (const key of declared)
+            forwardMember(key);
+    }
+    for (const key of replaced) {
+        Object.defineProperty(forward, key, {
+            value: overrides[key],
+            enumerable: true,
+            configurable: true,
+            writable: true,
+        });
+    }
+    return forward;
+}

package/dist/lab/composition-rules.d.ts

@@ -0,0 +1,5 @@
+import type { LabConfig } from "./types.js";
+/** The first composition rule a config breaks, in the parser's order, or null. */
+export declare function compositionReason(config: LabConfig): string | null;
+/** Why a this-repo lab cannot run live. The parser and the preview planner both refuse with it. */
+export declare const THIS_REPO_DRY_RUN_ONLY = "this-repo labs are dry-run only; use a clone or app-url subject for a live run.";