humanish 0.104.3 → 0.106.0

package/dist/routes/computer-use/single-bundle.js

@@ -0,0 +1,393 @@
+import { participantAssignment } from "../../lab/participant-assignment.js";
+import { redactText } from "../../evidence/redaction.js";
+import {} from "../../run/status.js";
+import { REVIEW_SCHEMA, bundleArtifacts, bundleHead, } from "../../run/bundle.js";
+import {} from "../../run/streams.js";
+import { aggregateTaskFunnels, tallyParticipantOutcomes, withCuaReviewProvenance, } from "../../run/outcomes.js";
+import { describeSubjectState, participantFeedbackCandidates, phaseEventIdSuffix, publicSafeAppUrlLabel, subjectProvenanceMessage, } from "./bundle-parts.js";
+import { participantStatus as participantStatusFor } from "../../run/judge.js";
+import { buildRunCostSummary } from "../../run/cost-summary.js";
+import { participantEvent, participantIds, participantRecord, participantStream, } from "../../run/participant-records.js";
+/** The one participant's record and stream ids: sim-001 and stream-001. */
+const SINGLE = participantIds(0);
+/** The participant's runner: a hosted E2B desktop, a local VM desktop, or the in-process route. */
+function runnerSubstrate(args) {
+    return args.substrate ?? (args.desktopRoute === false ? "local-filesystem" : "e2b-desktop");
+}
+/** Where the participant's browser ran, as the bundle's summary and stream intent say it. */
+function browserPlace(args) {
+    switch (runnerSubstrate(args)) {
+        case "local-desktop":
+            return "in a browser on a local VM";
+        case "local-filesystem":
+            return "in process, with no desktop";
+        default:
+            return "in a hosted desktop browser";
+    }
+}
+/** Run-level cost ESTIMATE (advisory; omitted when nothing was priced and no sandbox ran). */
+function runCost(args) {
+    return buildRunCostSummary({
+        participants: args.session
+            ? [
+                {
+                    ...(args.participantId === undefined ? {} : { participantId: args.participantId }),
+                    trace: args.session.trace,
+                },
+            ]
+            : [],
+        desktopMinutes: args.desktopMinutes,
+        ...(args.desktopUsage === undefined ? {} : { desktops: [args.desktopUsage] }),
+    });
+}
+/** The participant's status, reason, last frame, geometry and screenshot mode, shared by its records. */
+function participantView(args, publicAppUrl) {
+    const status = args.inProgress === true
+        ? "running"
+        : args.session
+            ? args.session.status
+            : args.sessionError !== undefined
+                ? "failed"
+                : "contract_proof_only";
+    const reason = args.inProgress === true
+        ? "Live computer-use session is running; stream auth URL is available only through the attached Observer server."
+        : (args.session?.reason ??
+            args.sessionError ??
+            "Contract bundle only: dry-run produced the evidence shape without launching a desktop or spending provider tokens.");
+    const lastScreenshot = args.screenshots[args.screenshots.length - 1];
+    const desktopGeometry = args.desktopRoute === false
+        ? undefined
+        : (args.desktopGeometry ?? {
+            screen: { requested: { width: args.resolution[0], height: args.resolution[1] } },
+        });
+    // Honest labels (invariant 6: claims match mechanism): every screenshot label names the
+    // run's ACTUAL mode. The session trace is the evidence-of-record; the capture policy covers
+    // frames written before a mid-session failure produced a trace.
+    const traceScreenshotMode = args.session?.trace.redaction.screenshots;
+    const screenshotMode = traceScreenshotMode === "raw" || traceScreenshotMode === "blurred"
+        ? traceScreenshotMode
+        : (args.captureRedaction ?? "raw");
+    return {
+        publicAppUrl,
+        status,
+        reason,
+        lastScreenshot,
+        desktopGeometry,
+        traceScreenshotMode,
+        screenshotMode,
+    };
+}
+function singleSimulation(args, view) {
+    const { publicAppUrl, status, reason } = view;
+    return participantRecord(SINGLE, 1, {
+        personaId: args.persona.id,
+        scenarioId: `cua-${args.labId}`,
+        status,
+        streamKind: "browser",
+        mode: "browser-sim",
+        progress: args.inProgress === true ? 20 : 100,
+        currentStep: reason,
+        summary: args.session
+            ? `Computer-use actor (${args.actorId}) drove the subject app ${browserPlace(args)}; ${args.session.completionReason}.`
+            : args.inProgress === true
+                ? `Computer-use actor (${args.actorId}) is driving the subject app ${browserPlace(args)}.`
+                : args.sessionError !== undefined
+                    ? `Computer-use lab failed before a terminal session verdict: ${args.sessionError}`
+                    : `Contract participant for the computer-use actor (${args.actorId}) against ${publicAppUrl}.`,
+        startedAt: args.createdAt,
+        updatedAt: args.createdAt,
+    });
+}
+function singleStream(args, view) {
+    const { publicAppUrl, status, reason, lastScreenshot, desktopGeometry, screenshotMode } = view;
+    return participantStream(SINGLE, {
+        ...(args.assignment === undefined
+            ? {}
+            : { assignment: participantAssignment(args.assignment) }),
+        ...(args.actorType === undefined ? {} : { actorType: args.actorType }),
+        ...(args.surface === undefined ? {} : { surface: args.surface }),
+        ...(args.caseGroup === undefined ? {} : { caseGroup: args.caseGroup }),
+        kind: "browser",
+        label: `CUA browser — ${args.labId}`,
+        status,
+        transport: "snapshot",
+        updatedAt: args.createdAt,
+        embed: lastScreenshot
+            ? { kind: "screenshot", url: lastScreenshot, title: `CUA desktop (${screenshotMode})` }
+            : { kind: "placeholder", title: "CUA desktop" },
+        ...(desktopGeometry?.viewport === undefined
+            ? {}
+            : {
+                viewport: {
+                    width: desktopGeometry.viewport.width,
+                    height: desktopGeometry.viewport.height,
+                    deviceScaleFactor: desktopGeometry.viewport.deviceScaleFactor,
+                    ...(args.isMobile === undefined ? {} : { isMobile: args.isMobile }),
+                },
+            }),
+        ...(desktopGeometry === undefined ? {} : { desktopGeometry }),
+        ...(args.recording === undefined ? {} : { recording: args.recording }),
+        ui: {
+            route: publicAppUrl,
+            intent: `Watch the computer-use actor drive the subject app ${browserPlace(args)}.`,
+            state: reason,
+            ...(args.session ? { actorStatus: args.session.status } : {}),
+            ...(lastScreenshot ? { screenshotUrl: lastScreenshot } : {}),
+        },
+        // The seam this lab exists to fill: the provider-neutral actor evidence projection.
+        ...(args.session ? { actor: args.session.trace } : {}),
+        artifacts: [
+            { label: "run bundle", path: "run.json", kind: "bundle" },
+            { label: "review", path: "review.md", kind: "review" },
+            { label: "events", path: "events.ndjson", kind: "events" },
+            ...(args.traceArtifactPath
+                ? [{ label: "actor trace", path: args.traceArtifactPath, kind: "trace" }]
+                : []),
+            ...(args.commsArtifactPath
+                ? [{ label: "comms thread", path: args.commsArtifactPath, kind: "log" }]
+                : []),
+            ...(args.recording
+                ? [{ label: "desktop recording", path: args.recording.path, kind: "recording" }]
+                : []),
+            ...args.screenshots.map((screenshot, index) => ({
+                label: `screenshot ${String(index + 1).padStart(2, "0")} (${screenshotMode})`,
+                path: screenshot,
+                kind: "screenshot",
+            })),
+        ],
+    }, args.participantId ?? "lane-01");
+}
+function singleEvents(args, view) {
+    const { publicAppUrl, desktopGeometry } = view;
+    const events = [
+        {
+            id: "event-000-created",
+            at: args.createdAt,
+            level: "info",
+            type: "cua-lab.run.created",
+            message: `Created computer-use lab run for ${args.labId} (actor ${args.actorId}).`,
+        },
+        args.subjectProvenance
+            ? participantEvent(SINGLE, {
+                id: "event-001-subject",
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.provenance",
+                // HONEST WORDING: claim "cloned/packed and served" only when it actually happened.
+                message: `${subjectProvenanceMessage(args.subjectProvenance, publicAppUrl, args.dryRun, args.session !== undefined)} (subject env names: ${args.subjectProvenance.envNames.length > 0 ? args.subjectProvenance.envNames.join(", ") : "none"}; values never persisted); state: ${describeSubjectState(args.subjectProvenance.state, args.dryRun)}.`,
+            })
+            : participantEvent(SINGLE, {
+                id: "event-001-subject",
+                at: args.createdAt,
+                level: "info",
+                type: "cua-lab.subject.declared",
+                // Invariant 5: declare what the subject WAS, including the ABSENCE of a pin. A
+                // local-app / in-process subject is an already-running LOCAL dev server the caller
+                // provisioned; it cannot be commit-pinned, so its provenance is honestly UNPINNED and
+                // no E2B desktop was created. A plain app-url entry runs inside the desktop sandbox, or,
+                // on the local VM, reaches the host's loopback from the VM's browser.
+                message: args.entryKind === "local-app"
+                    ? `Subject app declared at ${publicAppUrl} (already-running LOCAL dev server driven in-process; NO clone, NO E2B desktop). Provenance: caller-provisioned and UNPINNED — a running dev server cannot be commit-pinned.`
+                    : runnerSubstrate(args) === "local-desktop"
+                        ? `Subject app declared at ${publicAppUrl} (the host's loopback, opened from a browser on a local VM).`
+                        : `Subject app declared at ${publicAppUrl} (loopback inside the desktop sandbox).`,
+            }),
+        args.session
+            ? participantEvent(SINGLE, {
+                id: "event-002-session",
+                at: args.createdAt,
+                level: args.session.status === "passed" ? "info" : "warn",
+                type: `cua-lab.session.${args.session.completionReason}`,
+                message: `${args.session.status}: ${args.session.reason}`,
+            })
+            : args.inProgress === true
+                ? participantEvent(SINGLE, {
+                    id: "event-002-running",
+                    at: args.createdAt,
+                    level: "info",
+                    type: "cua-lab.session.running",
+                    message: "Live computer-use session is running; terminal evidence has not been written yet.",
+                })
+                : args.sessionError !== undefined
+                    ? participantEvent(SINGLE, {
+                        id: "event-002-session",
+                        at: args.createdAt,
+                        level: "error",
+                        type: "cua-lab.session.error",
+                        message: args.sessionError,
+                    })
+                    : participantEvent(SINGLE, {
+                        id: "event-002-contract",
+                        at: args.createdAt,
+                        level: "info",
+                        type: "cua-lab.contract.ready",
+                        message: "Dry-run contract bundle ready; switch scenario.mode to live for a real desktop session.",
+                    }),
+    ];
+    const record = (event) => events.push(participantEvent(SINGLE, event));
+    // Persisted phase trail (real boot timing, not just a coarse provenance sentence): one
+    // RunEvent per COMPLETED phase boundary (started events never persist here; they carry no
+    // durationMs). ok:false phases warn rather than error, since the failing phase's own thrown
+    // error already becomes the terminal cua-lab.session.error event above.
+    let phaseEventSeq = 3;
+    for (const phase of args.phaseEvents ?? []) {
+        record({
+            id: `event-${String(phaseEventSeq++).padStart(3, "0")}-phase-${phaseEventIdSuffix(phase.type)}`,
+            at: phase.at,
+            level: phase.ok === false ? "warn" : "info",
+            type: phase.type,
+            message: phase.durationMs === undefined ? phase.message : `${phase.message} (${phase.durationMs}ms)`,
+        });
+    }
+    for (const warning of desktopGeometry?.warnings ?? []) {
+        record({
+            id: `event-${String(phaseEventSeq++).padStart(3, "0")}-geometry-warning`,
+            at: args.createdAt,
+            level: "warn",
+            type: "cua-lab.geometry.warning",
+            message: warning,
+        });
+    }
+    return events;
+}
+function singleReview(args, view, stream) {
+    const { reason } = view;
+    // A funnel with a denominator of one is still the funnel — and its absence stays honest: no
+    // declared protocol (or a dry run) means no `tasks` field, never an empty one.
+    const singleStudyTasks = args.inProgress !== true && args.session?.trace.taskFunnel !== undefined
+        ? aggregateTaskFunnels([args.session.trace.taskFunnel])
+        : undefined;
+    // What happened to the participant, as the LANE judged it — the same rule the fan-out roll-up
+    // applies (participantStatusForOutcome). Before #476 this read the actor's own status, so a
+    // run the lane refused as "not a credible pass" was written up as verdict pass, 1/1 reached
+    // the goal, and every projection of the bundle (Observer tally, `runs`, the status index)
+    // repeated it. Found on a real drawDB run whose participant wrote "Blocked after partial
+    // completion".
+    const participantStatus = args.session === undefined
+        ? undefined
+        : participantStatusFor(args.session.status, args.credibility);
+    const credibilityNote = args.session === undefined || participantStatus === args.session.status
+        ? undefined
+        : args.credibility?.noEngagement === true
+            ? "Not counted as a pass: the participant took no actions and said nothing."
+            : "Not counted as a pass: the participant's final message described a blocker.";
+    const review = withCuaReviewProvenance({
+        schema: REVIEW_SCHEMA,
+        verdict: args.verdict,
+        // One lane is still a study with a denominator of one, and saying so keeps a single-lane
+        // result from being read as though it generalized.
+        ...(participantStatus !== undefined && args.inProgress !== true
+            ? {
+                participants: tallyParticipantOutcomes([participantStatus], [args.credibility?.reportedFriction === true]),
+            }
+            : {}),
+        ...(singleStudyTasks === undefined ? {} : { tasks: singleStudyTasks }),
+        summary: credibilityNote === undefined ? reason : `${credibilityNote} ${reason}`,
+        gaps: args.session || args.sessionError !== undefined
+            ? []
+            : args.inProgress === true
+                ? ["Live desktop session is still running."]
+                : ["Live desktop session not yet run (dry-run contract only)."],
+    }, [stream]);
+    return review;
+}
+/**
+ * The bundle of a single-participant run: one participant and no rerun. buildCuaRunBundle
+ * (bundle.ts) maps the run's base and state into these arguments.
+ */
+export function buildSingleParticipantBundle(args) {
+    const publicAppUrl = publicSafeAppUrlLabel(args.appUrl);
+    const cost = runCost(args);
+    const view = participantView(args, publicAppUrl);
+    const { traceScreenshotMode, screenshotMode } = view;
+    const simulation = singleSimulation(args, view);
+    const stream = singleStream(args, view);
+    const events = singleEvents(args, view);
+    const review = singleReview(args, view, stream);
+    return {
+        ...bundleHead({
+            ...(args.realEmail && !args.dryRun
+                ? { publication: { restrictions: ["real-communications"] } }
+                : {}),
+            runId: args.runId,
+            mode: args.dryRun ? "dry-run" : "live",
+            participants: 1,
+            createdAt: args.createdAt,
+            ...(args.lab === undefined ? {} : { lab: args.lab }),
+            source: args.source,
+        }),
+        persona: {
+            id: args.persona.id,
+            name: `Computer-use operator (${args.persona.id})`,
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest,
+        },
+        scenario: {
+            id: `cua-${args.labId}`,
+            title: args.labTitle ?? `Computer-use lab: ${args.labId}`,
+            goal: redactText(args.mission),
+            source: `lab:${args.labId}`,
+            sourceDigest: args.persona.promptDigest,
+        },
+        lifecycle: [
+            {
+                at: args.createdAt,
+                event: "cua-lab.run.created",
+                message: `Created computer-use lab run with one participant in a desktop browser (actor ${args.actorId}).`,
+            },
+        ],
+        simulations: [simulation],
+        streams: [stream],
+        events,
+        redaction: {
+            status: "passed",
+            notes: traceScreenshotMode === "raw"
+                ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are FULL-FIDELITY (raw), retained for local use — NOT redacted for publishing; set policies.redactScreenshots: true to blur a share-as-is bundle."
+                : traceScreenshotMode === "blurred"
+                    ? "Typed text recorded as length only and reasoning/messages pass through text redaction. Screenshots are blurred at capture (policies.redactScreenshots: true) for a share-as-is bundle."
+                    : args.screenshots.length > 0
+                        ? `Session ended before a trace was recorded; ${args.screenshots.length} already-written frame(s) follow the capture policy (${screenshotMode}). Typed text is recorded as length only and reasoning/messages pass through text redaction.`
+                        : "No screenshots captured. Typed text is recorded as length only and reasoning/messages pass through text redaction whenever a session runs.",
+        },
+        artifacts: bundleArtifacts(),
+        review,
+        // What the participant reported, when it reported anything (#392). Dry-run and in-progress
+        // bundles carry none — there is no participant yet to quote.
+        feedbackCandidates: args.dryRun || args.inProgress === true
+            ? []
+            : participantFeedbackCandidates({
+                runId: args.runId,
+                scenarioId: `cua-${args.labId}`,
+                adapterId: args.labId,
+                goal: redactText(args.mission),
+                substrate: runnerSubstrate(args),
+                participants: [
+                    {
+                        participantId: args.participantId ?? "lane-01",
+                        streamId: SINGLE.streamId,
+                        personaId: args.persona.id,
+                        ...(args.session === undefined ? {} : { session: args.session }),
+                        ...(args.traceArtifactPath === undefined
+                            ? {}
+                            : { traceArtifactPath: args.traceArtifactPath }),
+                        screenshots: args.screenshots,
+                        ...(args.commsArtifactPath === undefined
+                            ? {}
+                            : { commsArtifactPath: args.commsArtifactPath }),
+                    },
+                ],
+            }),
+        // Custom desktop image provenance (omitted on the stock-template default → byte-stable).
+        ...(args.desktopTemplate === undefined ? {} : { desktopTemplate: args.desktopTemplate }),
+        ...(args.desktopBrowser === undefined ? {} : { desktopBrowser: args.desktopBrowser }),
+        ...(args.providerResources === undefined || args.providerResources.length === 0
+            ? {}
+            : { providerResources: args.providerResources }),
+        // Structured subject provenance (invariant 5): code pin + state story. Uniform and
+        // honest on app-url bundles too — the caller minted the URL, its state is the caller's.
+        // CuaSubjectProvenanceArg's two variants (clone, local-tree) are already RunSubjectProvenance-
+        // shaped, so no reconstruction is needed beyond the app-url fallback.
+        subject: args.subjectProvenance ?? { source: "app-url", state: { provenance: "undeclared" } },
+        ...(cost === undefined ? {} : { cost }),
+    };
+}

package/dist/routes/computer-use/subject-projection.d.ts

@@ -0,0 +1,51 @@
+import type { ComputerUsePlan } from "../../lab/plan-types.js";
+import type { LabSubjectState } from "../../lab/types.js";
+import { type RunSubjectProvenance, type RunSubjectStateStepRecord } from "../../run/bundle.js";
+import { type LocalTreeArchive } from "../../subject/local-tree-archive.js";
+import { type CuaSubjectRoute } from "./plan.js";
+import { type DesktopParticipantRun, type CuaSubjectProjection, type CuaSubjectProvenanceArg, type ParticipantRunOutcome } from "./types.js";
+/**
+ * Each lane's subject projection. A lane's outcome adds the subject commit it resolved and the
+ * state steps it executed; without outcomes (dry run, or a run still in progress) the declared
+ * state is projected as not yet run.
+ */
+export declare function projectParticipantSubjects(args: {
+    plan: ComputerUsePlan;
+    subjectRoute: CuaSubjectRoute;
+    publicRepo?: string;
+    localTreeArchive?: LocalTreeArchive;
+    runs: readonly DesktopParticipantRun[];
+    outcomes: readonly ParticipantRunOutcome[] | undefined;
+    dryRun: boolean;
+}): CuaSubjectProjection[];
+/**
+ * Resolve the bundle's state marker from the declaration and what actually ran.
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
+ * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
+ * contract bundles and failed live provisioning); no declaration → "undeclared".
+ */
+export declare function resolveSubjectState(args: {
+    declared: LabSubjectState | undefined;
+    dryRun: boolean;
+    executed: RunSubjectStateStepRecord[];
+}): RunSubjectProvenance["state"];
+/** Narrow a resolved CuaSubjectProjection into the shape buildSingleParticipantBundle's
+ *  subjectProvenance param wants (provisioned-route sources only; app-url stays undeclared, the
+ *  default branch that builder already handles). */
+export declare function subjectProvenanceArg(subject: CuaSubjectProjection, publicRepo: string | undefined, subjectEnvNames: string[]): CuaSubjectProvenanceArg | undefined;
+/**
+ * The run-level subject for the top level and the bundle. Local-tree lanes all pack from the same
+ * once-per-run archive, so every lane already carries the identical archiveSha256/commit/dirty and
+ * the first lane's projection is the aggregate. Clone lanes each resolve their own commit; the
+ * aggregate carries it only when every lane agrees, and warns when they diverge.
+ */
+export declare function aggregateCuaSubject(args: {
+    subjects: readonly CuaSubjectProjection[];
+    outcomes: readonly ParticipantRunOutcome[] | undefined;
+    participantCount: number;
+    dryRun: boolean;
+}): {
+    subject: CuaSubjectProjection;
+    warnings: string[];
+};

package/dist/routes/computer-use/subject-projection.js

@@ -0,0 +1,159 @@
+// Each lane's subject projection and the subject-state marker, from the declared subject and what
+// the lanes ran; the run-level subject aggregated from them; and the provenance argument the
+// bundle builders take.
+import { commandDigestOf } from "../../subject/state.js";
+import { cuaDeclaredState } from "./plan.js";
+import {} from "../../run/bundle.js";
+import {} from "../../subject/local-tree-archive.js";
+import {} from "./plan.js";
+import {} from "./types.js";
+/**
+ * Each lane's subject projection. A lane's outcome adds the subject commit it resolved and the
+ * state steps it executed; without outcomes (dry run, or a run still in progress) the declared
+ * state is projected as not yet run.
+ */
+export function projectParticipantSubjects(args) {
+    const { subjectRoute, publicRepo, localTreeArchive } = args;
+    const declaredState = cuaDeclaredState(args.plan);
+    return args.runs.map((_spec, index) => {
+        const outcome = args.outcomes?.[index];
+        const subjectState = resolveSubjectState({
+            declared: subjectRoute.provisionedRoute ? declaredState : undefined,
+            dryRun: args.dryRun,
+            executed: outcome?.stateStepRecords ?? [],
+        });
+        return participantSubjectProjection({
+            cloneRoute: subjectRoute.cloneRoute,
+            localTreeRoute: subjectRoute.localTreeRoute,
+            ...(publicRepo === undefined ? {} : { publicRepo }),
+            subjectEnvNames: subjectRoute.subjectEnvNames,
+            ...(outcome?.subjectCommit === undefined ? {} : { subjectCommit: outcome.subjectCommit }),
+            ...(localTreeArchive === undefined ? {} : { localTreeArchive }),
+            subjectState,
+        });
+    });
+}
+/**
+ * Resolve the bundle's state marker from the declaration and what actually ran.
+ * Precedence: external declared → "unpinned" (seed records, if any, stay attached — a
+ * migrated external DB is still unpinned overall); else seed declared → "seeded" only when
+ * every declared step executed ok on a live run, otherwise "declared-not-run" (dry-run
+ * contract bundles and failed live provisioning); no declaration → "undeclared".
+ */
+export function resolveSubjectState(args) {
+    const declared = args.declared;
+    if (!declared) {
+        return { provenance: "undeclared" };
+    }
+    const declaredSeed = declared.seed ?? [];
+    const external = declared.external ?? [];
+    // Dry-run: nothing executes (no sandbox) — record the DECLARED recipe: name, phase, and
+    // command digest only, with NO execution fields.
+    const seed = args.dryRun
+        ? declaredSeed.map((step) => ({
+            name: step.name,
+            when: step.when ?? "before-start",
+            commandDigest: commandDigestOf(step.command),
+        }))
+        : args.executed;
+    const allRanOk = !args.dryRun &&
+        declaredSeed.length > 0 &&
+        seed.length === declaredSeed.length &&
+        seed.every((record) => record.ok === true);
+    const provenance = external.length > 0
+        ? "unpinned"
+        : declaredSeed.length === 0
+            ? "undeclared"
+            : allRanOk
+                ? "seeded"
+                : "declared-not-run";
+    return {
+        provenance,
+        ...(seed.length > 0 ? { seed } : {}),
+        ...(external.length > 0 ? { externalEnvNames: external } : {}),
+    };
+}
+/** Build the per-lane subject projection (invariant 5). Local-tree lanes all share ONE
+ *  host-packed archive, so every lane's projection carries the identical archiveSha256/
+ *  commit/dirty (no per-lane divergence is possible, unlike the clone route's per-lane
+ *  in-sandbox commit). */
+function participantSubjectProjection(args) {
+    if (args.cloneRoute && args.publicRepo) {
+        return {
+            source: "clone",
+            repo: args.publicRepo,
+            ...(args.subjectCommit === undefined ? {} : { commit: args.subjectCommit }),
+            envNames: args.subjectEnvNames,
+            state: args.subjectState,
+        };
+    }
+    if (args.localTreeRoute) {
+        const archive = args.localTreeArchive;
+        return {
+            source: "local-tree",
+            ...(archive === undefined ? {} : { archiveSha256: archive.archiveSha256 }),
+            ...(archive?.git === undefined
+                ? {}
+                : { commit: archive.git.commit, dirty: archive.git.dirty }),
+            envNames: args.subjectEnvNames,
+            state: args.subjectState,
+        };
+    }
+    return { source: "app-url", state: args.subjectState };
+}
+/** Narrow a resolved CuaSubjectProjection into the shape buildSingleParticipantBundle's
+ *  subjectProvenance param wants (provisioned-route sources only; app-url stays undeclared, the
+ *  default branch that builder already handles). */
+export function subjectProvenanceArg(subject, publicRepo, subjectEnvNames) {
+    if (subject.source === "clone" && publicRepo) {
+        return {
+            source: "clone",
+            repo: publicRepo,
+            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
+            envNames: subjectEnvNames,
+            state: subject.state,
+        };
+    }
+    if (subject.source === "local-tree") {
+        return {
+            source: "local-tree",
+            ...(subject.archiveSha256 === undefined ? {} : { archiveSha256: subject.archiveSha256 }),
+            ...(subject.commit === undefined ? {} : { commit: subject.commit }),
+            ...(subject.dirty === undefined ? {} : { dirty: subject.dirty }),
+            envNames: subjectEnvNames,
+            state: subject.state,
+        };
+    }
+    return undefined;
+}
+/**
+ * The run-level subject for the top level and the bundle. Local-tree lanes all pack from the same
+ * once-per-run archive, so every lane already carries the identical archiveSha256/commit/dirty and
+ * the first lane's projection is the aggregate. Clone lanes each resolve their own commit; the
+ * aggregate carries it only when every lane agrees, and warns when they diverge.
+ */
+export function aggregateCuaSubject(args) {
+    const { subjects, outcomes, participantCount, dryRun } = args;
+    const first = subjects[0];
+    if (first.source !== "clone")
+        return { subject: first, warnings: [] };
+    const commits = (outcomes ?? [])
+        .map((outcome) => outcome.subjectCommit)
+        .filter((commit) => commit !== undefined);
+    const unanimous = !dryRun && commits.length === participantCount && new Set(commits).size === 1;
+    const warnings = !dryRun && participantCount > 1 && new Set(commits).size > 1
+        ? [
+            "Fan-out participants resolved DIVERGENT subject commits, so the top-level subject.commit is omitted; see each participant's provenance in result.lanes for its pinned commit.",
+        ]
+        : [];
+    return {
+        subject: {
+            source: "clone",
+            ...(first.repo === undefined ? {} : { repo: first.repo }),
+            ...(first.envNames === undefined ? {} : { envNames: first.envNames }),
+            state: first.state,
+            ...(unanimous && commits[0] !== undefined ? { commit: commits[0] } : {}),
+        },
+        warnings,
+    };
+}