humanish 0.89.1 → 0.91.0

package/README.md

@@ -50,7 +50,9 @@ npx humanish observe --run latest --open
 
 Existing `E2B_API_KEY` and `OPENAI_API_KEY` environment variables also work.
 `try-live` clones and studies drawDB, not your project. Its **$2 cap covers
-estimated model spend**; hosted desktop time is additional. Caps are checked
+estimated participant model spend**. Post-run analysis defaults to a separate
+**$3 admission estimate limit**; set `review.analysis: false` to disable it.
+Hosted desktop time is additional. Participant caps are checked
 between turns and are not provider billing ceilings. Allow a few minutes for
 the app to build and the participant to work. See [budgets and privacy](https://humanish.dev/docs/budgets-and-privacy).
 
@@ -104,6 +106,23 @@ beside Participants in Observer, with evidence links and separate participant
 feedback. See the [analysis contract](docs/contracts/study-analysis.md) for
 coverage limits, estimated cost controls, corrections and sharing behavior.
 
+Supported live studies generate findings automatically after participants finish,
+using a separate $3 admission estimate limit with `gpt-6-astra` and high reasoning.
+This is additional to participant execution costs, and is not a hard provider
+billing cap. To disable the extra request:
+
+```yaml
+review:
+  analysis: false
+```
+
+`humanish run <lab>`, `humanish lab run <lab>`, `humanish watch <lab>`, and live
+starts in the TUI share this default. Dry runs and unsupported routes dispatch
+nothing. Without `OPENAI_API_KEY`, default analysis is skipped and a successful
+recording stays successful. Opening the TUI or Observer never starts a request.
+See [automatic analysis](docs/product/automatic-analysis.md) for configuration,
+cancellation, and failure behavior.
+
 ## Public-Safety Boundary
 
 Humanish is designed for public repositories and public issue queues. The

package/dist/automatic-analysis-completion.d.ts

@@ -0,0 +1,25 @@
+import { type PreparedRunArtifactPaths } from "./run-paths.js";
+import type { StudyAnalysisConfig } from "./study-analysis.js";
+import { runAutomaticStudyAnalysis, type AutomaticStudyAnalysisDeps } from "./automatic-study-analysis.js";
+import type { AutomaticStudyAnalysisOutcome } from "./study-analysis-job.js";
+export interface AutomaticAnalysisHooks {
+    /** Provider/test dependencies apply only to analysis, never to the participant. */
+    deps?: AutomaticStudyAnalysisDeps;
+    /** Called after the source is finalized; the returned cleanup always runs. */
+    onStart?: () => void | (() => void);
+    run?: typeof runAutomaticStudyAnalysis;
+}
+export interface AutomaticAnalysisResult {
+    automaticAnalysis?: AutomaticStudyAnalysisOutcome;
+    /** Distinguishes the default missing-key skip from failure of an explicit request. */
+    automaticAnalysisTrigger?: "default" | "explicit";
+}
+/** Internal producer receipt: call only after final source publication, never for an early refusal. */
+export declare function markFinalizedStudyResult<T extends object>(result: T, prepared: PreparedRunArtifactPaths): T;
+/** One post-completion boundary shared by all live recording producers. */
+export declare function completeAutomaticAnalysis<T extends {
+    cwd: string;
+    runId: string;
+    dryRun: boolean;
+}>(result: T, config: StudyAnalysisConfig | undefined, hooks?: AutomaticAnalysisHooks, trigger?: "default" | "explicit"): Promise<T & AutomaticAnalysisResult>;
+export declare function automaticAnalysisSucceeded(result: AutomaticAnalysisResult): boolean;

package/dist/automatic-analysis-completion.js

@@ -0,0 +1,56 @@
+import path from "node:path";
+import { validatePreparedRunRootIdentity } from "./run-paths.js";
+import { runAutomaticStudyAnalysis } from "./automatic-study-analysis.js";
+const finalizedResults = new WeakMap();
+/** Internal producer receipt: call only after final source publication, never for an early refusal. */
+export function markFinalizedStudyResult(result, prepared) {
+    finalizedResults.set(result, prepared);
+    return result;
+}
+/** One post-completion boundary shared by all live recording producers. */
+export async function completeAutomaticAnalysis(result, config, hooks, trigger = "explicit") {
+    if (config === undefined)
+        return result;
+    const origin = trigger === "default" ? { automaticAnalysisTrigger: trigger } : {};
+    if (result.dryRun)
+        return { ...result, ...origin, automaticAnalysis: { state: "skipped", reason: "analysis_dry_run" } };
+    // An early refusal can echo a caller-supplied ID belonging to an older run.
+    // Require this invocation's internal final-publication receipt before reading that ID.
+    const prepared = finalizedResults.get(result);
+    if (!result.runId || result.runId === "not-created" || prepared === undefined) {
+        return { ...result, ...origin, automaticAnalysis: { state: "skipped", reason: "analysis_source_unavailable" } };
+    }
+    let cleanup = undefined;
+    try {
+        cleanup = hooks?.onStart?.();
+        try {
+            await validatePreparedRunRootIdentity(prepared);
+        }
+        catch {
+            return { ...result, ...origin, automaticAnalysis: { state: "failed", reason: "analysis_source_changed" } };
+        }
+        const sourceCwd = path.dirname(path.dirname(prepared.physicalRunsRoot));
+        const automaticAnalysis = await (hooks?.run ?? runAutomaticStudyAnalysis)(sourceCwd, result.runId, config, { ...hooks?.deps, ...(trigger === "default" ? { defaultRequest: true } : {}), expectedRun: prepared });
+        return { ...result, ...origin, automaticAnalysis };
+    }
+    catch {
+        // Preserve the producer result. Never put a hook exception or provider response in the envelope.
+        return { ...result, ...origin, automaticAnalysis: { state: "failed", reason: "analysis_automatic_failed" } };
+    }
+    finally {
+        try {
+            cleanup?.();
+        }
+        catch { /* Cleanup cannot erase accounting or the completed recording. */ }
+    }
+}
+export function automaticAnalysisSucceeded(result) {
+    const value = result.automaticAnalysis;
+    if (value === undefined)
+        return true;
+    if (value.state === "skipped")
+        return value.reason === "analysis_dry_run"
+            || (result.automaticAnalysisTrigger === "default" && ["AUTOMATIC_ANALYSIS_KEY_MISSING", "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE"].includes(value.reason ?? ""));
+    return (value.state === "complete" || value.state === "partial") && value.result?.ok === true;
+}
+//# sourceMappingURL=automatic-analysis-completion.js.map

package/dist/automatic-analysis-completion.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automatic-analysis-completion.js","sourceRoot":"","sources":["../src/automatic-analysis-completion.ts"],"names":[],"mappings":"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"}

package/dist/automatic-analysis-config.d.ts

@@ -0,0 +1,25 @@
+import type { StudyAnalysisConfig } from "./study-analysis.js";
+/** A separately budgeted review after a live participant study. */
+export interface LabAnalysis {
+    maxCostUsd: number;
+    model?: string;
+    question?: string;
+    timeoutMs?: number;
+    maxOutputTokens?: number;
+}
+/** Called for parsed manifests AND direct library configs, before participant execution. */
+export declare function resolveAutomaticAnalysis(raw: unknown): {
+    ok: true;
+    config: StudyAnalysisConfig | undefined;
+} | {
+    ok: false;
+    message: string;
+};
+export interface AutomaticAnalysisBudget {
+    model: string;
+    maxCostUsd: number;
+    trigger: "default" | "explicit";
+}
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
+export declare function automaticAnalysisBudget(raw: unknown, backend: string): AutomaticAnalysisBudget | undefined;
+export declare function formatAutomaticAnalysisBudget(budget: AutomaticAnalysisBudget): string;

package/dist/automatic-analysis-config.js

@@ -0,0 +1,44 @@
+import { SUPPORTED_STUDY_ANALYSIS_MODELS } from "./study-analysis-engine.js";
+import { containsSensitive } from "./redaction.js";
+const MODELS = new Set(SUPPORTED_STUDY_ANALYSIS_MODELS);
+const FIELDS = new Set(["maxCostUsd", "model", "question", "timeoutMs", "maxOutputTokens"]);
+/** Called for parsed manifests AND direct library configs, before participant execution. */
+export function resolveAutomaticAnalysis(raw) {
+    if (raw === false)
+        return { ok: true, config: undefined };
+    if (raw === undefined)
+        raw = { maxCostUsd: 3 };
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)
+        || Object.keys(raw).some(key => !FIELDS.has(key))) {
+        return { ok: false, message: "review.analysis must be false or a mapping containing only maxCostUsd, model, question, timeoutMs and maxOutputTokens." };
+    }
+    const value = raw;
+    const { maxCostUsd } = value;
+    const model = value.model === undefined ? "gpt-6-astra" : value.model;
+    const question = value.question === undefined ? null : value.question;
+    const timeoutMs = value.timeoutMs === undefined ? 300_000 : value.timeoutMs;
+    const maxOutputTokens = value.maxOutputTokens === undefined ? 16_384 : value.maxOutputTokens;
+    if (typeof maxCostUsd !== "number" || !Number.isFinite(maxCostUsd) || maxCostUsd <= 0 || maxCostUsd > 1000
+        || typeof model !== "string" || !MODELS.has(model)
+        || typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 600_000
+        || typeof maxOutputTokens !== "number" || !Number.isSafeInteger(maxOutputTokens) || maxOutputTokens < 256 || maxOutputTokens > 32_768
+        || (value.question !== undefined && (typeof question !== "string" || question.length > 4000))) {
+        return { ok: false, message: "review.analysis requires a positive maxCostUsd up to 1000, a supported analysis model, timeoutMs 1–600000, maxOutputTokens 256–32768, and an optional question of at most 4000 characters." };
+    }
+    if (question !== null && containsSensitive(question)) {
+        return { ok: false, message: "review.analysis.question contains sensitive text and cannot be sent for analysis." };
+    }
+    return { ok: true, config: { model, maxCostUsd, timeoutMs, maxOutputTokens, question: question } };
+}
+/** Metadata only: resolving the future live-run budget never reads keys or dispatches. */
+export function automaticAnalysisBudget(raw, backend) {
+    if (!["cua", "scripted", "terminal", "shared-world", "concurrent-shared-world"].includes(backend))
+        return undefined;
+    const resolved = resolveAutomaticAnalysis(raw);
+    return resolved.ok && resolved.config ? { model: resolved.config.model, maxCostUsd: resolved.config.maxCostUsd,
+        trigger: raw === undefined ? "default" : "explicit" } : undefined;
+}
+export function formatAutomaticAnalysisBudget(budget) {
+    return `After live runs: ${budget.trigger} analysis · ${budget.model} · separate $${budget.maxCostUsd} admission estimate limit (not a provider billing cap). Set review.analysis: false to disable.`;
+}
+//# sourceMappingURL=automatic-analysis-config.js.map

package/dist/automatic-analysis-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automatic-analysis-config.js","sourceRoot":"","sources":["../src/automatic-analysis-config.ts"],"names":[],"mappings":"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"}

package/dist/automatic-study-analysis.d.ts

@@ -0,0 +1,15 @@
+import { type AnalyzeDeps } from "./study-analysis-service.js";
+import { type AutomaticStudyAnalysisView, type AutomaticStudyAnalysisOutcome, type AutomaticStudyAnalysisCancellation } from "./study-analysis-job.js";
+import type { StudyAnalysisConfig } from "./study-analysis.js";
+export type { AutomaticStudyAnalysisView, AutomaticStudyAnalysisOutcome, AutomaticStudyAnalysisCancellation } from "./study-analysis-job.js";
+export type AutomaticStudyAnalysisDeps = Omit<AnalyzeDeps, "analysisId" | "beforeDispatch"> & {
+    /** A missing default key records a skip before admission, preserving a successful recording. */
+    defaultRequest?: boolean;
+};
+/** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
+export declare function readAutomaticStudyAnalysis(cwd: string, runId: string): Promise<AutomaticStudyAnalysisView | undefined>;
+export declare function requestAutomaticStudyAnalysisCancellation(cwd: string, runId: string): Promise<AutomaticStudyAnalysisCancellation>;
+/** One permanent claim per completed run, consumed even when preparation/cancellation fails.
+ * Only the original producer calls this after all recording writes return.
+ * No file reader, restart recovery, Observer poll or export calls this function. */
+export declare function runAutomaticStudyAnalysis(cwdInput: string, runId: string, configInput: StudyAnalysisConfig, deps?: AutomaticStudyAnalysisDeps): Promise<AutomaticStudyAnalysisOutcome>;

package/dist/automatic-study-analysis.js

@@ -0,0 +1,187 @@
+import path from "node:path";
+import { renderObserver } from "./observer.js";
+import { resolveRunPath } from "./run.js";
+import { analyzeStudy, readCompletedStudyAnalysisSource, resolveStudyAnalysisRun } from "./study-analysis-service.js";
+import { STUDY_ANALYSIS_PROMPT_VERSION } from "./study-analysis-engine.js";
+import { hashStudyAnalysisValue } from "./study-analysis-validation.js";
+import { claimAutomaticStudyAnalysis, readAutomaticStudyAnalysisPrepared, requestAutomaticStudyAnalysisCancellationPrepared } from "./study-analysis-job.js";
+import { readStudyAnalysisExecution, readStudyAnalysisVersion } from "./study-analysis-store.js";
+const exactId = (runId) => runId !== "latest" && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(runId);
+const skipped = (reason) => ({ state: "skipped", reason });
+function hasParticipantEvidence(bundle) {
+    return bundle.streams.some(stream => {
+        // Terminal commands and transcript messages also include launcher output.
+        // Fresh producers count recognized participant runtime items separately.
+        if (stream.actor?.lane === "terminal")
+            return (stream.actor.counts.runtimeParticipantItems ?? 0) > 0;
+        return stream.actor?.items.some(item => ["screenshot", "ui_action", "command", "tool_call", "file_change", "approval"].includes(item.kind)
+            || (["message", "reasoning"].includes(item.kind) && !!item.text?.trim()));
+    });
+}
+/** Small read-only TUI/CLI projection. Neither this nor Observer can resume a job. */
+export async function readAutomaticStudyAnalysis(cwd, runId) {
+    if (!exactId(runId))
+        return undefined;
+    const prepared = await resolveRunPath(path.resolve(cwd), runId).catch(() => null);
+    return prepared ? readAutomaticStudyAnalysisPrepared(prepared) : undefined;
+}
+export async function requestAutomaticStudyAnalysisCancellation(cwd, runId) {
+    if (!exactId(runId))
+        return { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
+    const prepared = await resolveRunPath(path.resolve(cwd), runId).catch(() => null);
+    return prepared ? requestAutomaticStudyAnalysisCancellationPrepared(prepared)
+        : { requested: false, reason: "AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE" };
+}
+function outcomeOf(result) {
+    if (result.error?.code === "ANALYSIS_PUBLICATION_FAILED")
+        return { state: "failed", reason: "AUTOMATIC_ANALYSIS_PUBLICATION_FAILED", result };
+    if (result.status)
+        return { state: result.status, result, reason: result.reused ? "AUTOMATIC_ANALYSIS_REUSED"
+                : result.status === "partial" ? (result.error?.code === "analysis_admission_estimate_exceeded"
+                    ? "AUTOMATIC_ANALYSIS_ADMISSION_EXCEEDED" : result.ok ? "AUTOMATIC_ANALYSIS_LIMITATIONS" : "AUTOMATIC_ANALYSIS_FAILED")
+                    : result.status === "failed" ? "AUTOMATIC_ANALYSIS_FAILED"
+                        : result.status === "cancelled" ? "AUTOMATIC_ANALYSIS_CANCELLED" : null };
+    const code = result.error?.code;
+    if (code === "ANALYSIS_CANCELLED")
+        return { state: "cancelled", reason: "AUTOMATIC_ANALYSIS_CANCELLED", result };
+    if (code === "ANALYSIS_API_KEY_MISSING")
+        return { ...skipped("AUTOMATIC_ANALYSIS_KEY_MISSING"), result };
+    if (code === "ANALYSIS_BUSY")
+        return { ...skipped("AUTOMATIC_ANALYSIS_BUSY"), result };
+    if (code === "ANALYSIS_HISTORY_UNAVAILABLE")
+        return { ...skipped("AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE"), result };
+    if (code === "ANALYSIS_CONFIG_INVALID" || code === "ANALYSIS_QUESTION_UNSAFE" || code?.startsWith("analysis_")) {
+        return { ...skipped("AUTOMATIC_ANALYSIS_ADMISSION_REFUSED"), result };
+    }
+    return { state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN", result };
+}
+/** One permanent claim per completed run, consumed even when preparation/cancellation fails.
+ * Only the original producer calls this after all recording writes return.
+ * No file reader, restart recovery, Observer poll or export calls this function. */
+export async function runAutomaticStudyAnalysis(cwdInput, runId, configInput, deps = {}) {
+    if (!exactId(runId))
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    let cwd = path.resolve(cwdInput);
+    const prepared = await resolveStudyAnalysisRun(cwd, runId, deps.expectedRun).catch(() => null);
+    if (!prepared)
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    cwd = path.dirname(path.dirname(prepared.physicalRunsRoot));
+    let participantEvidence = false;
+    // Do not consume a future run's one claim while a producer is still writing it.
+    try {
+        const bytes = await readCompletedStudyAnalysisSource(cwd, prepared);
+        const bundle = JSON.parse(bytes.toString("utf8"));
+        if (bundle.streams.some(stream => stream.actor?.stopCause === "harness_aborted"))
+            return skipped("AUTOMATIC_ANALYSIS_ACTOR_CANCELLED");
+        participantEvidence = hasParticipantEvidence(bundle);
+    }
+    catch {
+        return skipped("AUTOMATIC_ANALYSIS_SOURCE_UNAVAILABLE");
+    }
+    const config = structuredClone(configInput);
+    let job;
+    try {
+        const claimed = await claimAutomaticStudyAnalysis(prepared, { configDigest: hashStudyAnalysisValue(config), promptVersion: STUDY_ANALYSIS_PROMPT_VERSION });
+        if (!claimed)
+            return skipped("AUTOMATIC_ANALYSIS_ALREADY_REQUESTED");
+        job = claimed;
+    }
+    catch {
+        return { state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    }
+    const controller = new AbortController();
+    const signal = deps.signal ? AbortSignal.any([deps.signal, controller.signal]) : controller.signal;
+    let polling = false;
+    let storageFailed = false;
+    let cancellationFailed = false;
+    const poll = async () => {
+        if (polling)
+            return;
+        polling = true;
+        try {
+            if (await job.cancellationRequested())
+                controller.abort();
+        }
+        catch {
+            cancellationFailed = true;
+            controller.abort();
+        }
+        finally {
+            polling = false;
+        }
+    };
+    const cancellationTimer = setInterval(() => { void poll(); }, 250);
+    cancellationTimer.unref();
+    const heartbeat = setInterval(() => {
+        void job.touch().catch(() => { storageFailed = true; controller.abort(); });
+    }, 5000);
+    heartbeat.unref();
+    let outcome;
+    try {
+        await poll();
+        const missingKey = !(deps.apiKey ?? process.env.OPENAI_API_KEY)?.trim();
+        if (deps.defaultRequest === true && (missingKey || !participantEvidence)) {
+            outcome = signal.aborted ? { state: "cancelled", reason: "AUTOMATIC_ANALYSIS_CANCELLED" }
+                : skipped(missingKey ? "AUTOMATIC_ANALYSIS_KEY_MISSING" : "AUTOMATIC_ANALYSIS_NO_PARTICIPANT_EVIDENCE");
+        }
+        else {
+            const result = await analyzeStudy(cwd, runId, { config }, {
+                ...deps, signal, expectedRun: prepared, analysisId: job.attemptId,
+                beforeDispatch: async (context) => {
+                    if (await job.cancellationRequested())
+                        controller.abort();
+                    if (signal.aborted)
+                        return;
+                    await job.update({ state: "running", analysisId: context.id, startedAt: new Date().toISOString(),
+                        sourceRunSha256: context.sourceRunSha256, inputDigest: context.inputDigest });
+                }
+            });
+            outcome = outcomeOf(result);
+        }
+        if (cancellationFailed)
+            outcome = { ...outcome, state: "unknown", reason: "AUTOMATIC_ANALYSIS_CANCELLATION_UNAVAILABLE" };
+        if (storageFailed)
+            outcome = { ...outcome, state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    }
+    catch {
+        outcome = { state: "unknown", reason: "AUTOMATIC_ANALYSIS_OUTCOME_UNKNOWN" };
+    }
+    finally {
+        clearInterval(cancellationTimer);
+        clearInterval(heartbeat);
+    }
+    try {
+        // Bind terminal metadata to the exact safely published execution. Reads never
+        // promote a completed-looking sidecar without rechecking these bindings.
+        const analysisId = outcome.result?.analysisId;
+        const [entry, receipt] = analysisId ? await Promise.all([
+            readStudyAnalysisVersion(prepared, analysisId), readStudyAnalysisExecution(prepared, analysisId)
+        ]) : [null, null];
+        await job.update({ state: outcome.state, reason: outcome.reason,
+            analysisId: analysisId ?? null,
+            ...(receipt === null ? {} : { sourceRunSha256: receipt.sourceRunSha256, inputDigest: receipt.inputDigest,
+                receiptSha256: hashStudyAnalysisValue(receipt) }),
+            ...(entry?.analysis ? { analysisSha256: hashStudyAnalysisValue(entry.analysis) } : {}) });
+        const persisted = await readAutomaticStudyAnalysisPrepared(prepared);
+        if (persisted?.state === "unknown")
+            outcome = { ...outcome, state: "unknown", reason: persisted.reason };
+    }
+    catch {
+        return { ...outcome, state: "unknown", reason: "AUTOMATIC_ANALYSIS_STORAGE_UNAVAILABLE" };
+    }
+    // The service may render while this owner is still running. Freeze the final
+    // job projection for direct file opening too, including no-request outcomes.
+    // A failed refresh must never erase the durable outcome or measured usage.
+    try {
+        const rendered = await renderObserver(cwd, runId, { open: false, expectedRun: prepared });
+        if (!rendered.ok)
+            throw new Error("AUTOMATIC_ANALYSIS_OBSERVER_UNAVAILABLE");
+    }
+    catch {
+        if (outcome.result)
+            outcome = { ...outcome, result: { ...outcome.result,
+                    warnings: [...outcome.result.warnings, "Automatic analysis status was saved, but Observer could not be refreshed. Run humanish observe again."] } };
+    }
+    return outcome;
+}
+//# sourceMappingURL=automatic-study-analysis.js.map

package/dist/automatic-study-analysis.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"automatic-study-analysis.js","sourceRoot":"","sources":["../src/automatic-study-analysis.ts"],"names":[],"mappings":"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"}

package/dist/concurrent-shared-world-lab.d.ts

@@ -1,3 +1,4 @@
+import { type AutomaticAnalysisHooks, type AutomaticAnalysisResult } from "./automatic-analysis-completion.js";
 import { type RunLabProvenance } from "./run-status.js";
 import { type CuaActorDescriptor } from "./actor-registry.js";
 import { type CuaLaneSpec, type LaneRunOutcome } from "./cua-actor-lab.js";
@@ -12,6 +13,7 @@ export declare const CONCURRENT_SHARED_WORLD_PROVIDER_METADATA: {
 };
 export declare const CONCURRENT_ATTRIBUTION_LIMITS: readonly ["concurrent", "best-effort-causal-attribution", "non-deterministic-shared-state", "window-and-snapshot-granularity", "contention-observed-not-proven-safe", "state-change-not-isolated-to-actors"];
 export interface RunConcurrentSharedWorldLabOptions {
+    automaticAnalysis?: AutomaticAnalysisHooks;
     /** Which manifest produced this run (#455); threaded into the status record + bundle. */
     lab?: RunLabProvenance;
     cwd: string;
@@ -28,7 +30,7 @@ export interface RunConcurrentSharedWorldLabOptions {
      *  (#316); core-stamped onto the bundle as evidence. Absent for library callers. */
     scorerProvenance?: RunScorerProvenance;
 }
-export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT"
+export type ConcurrentSharedWorldLabErrorCode = "HUMANISH_LAB_ANALYSIS_INVALID" | "HUMANISH_LAB_TASKS_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_ACTOR_UNSUPPORTED" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_INVALID" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_KEYS_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_SUBJECT_ENV_MISSING" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_GETHOST_UNAVAILABLE" | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_HANDOFF_TIMEOUT"
 /** A declared adopter-hosted comms catch (#328) did not answer as a humanish catch — fail closed
  *  BEFORE any actor spend, since the funnel would silently collect nothing. */
  | "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_COMMS_CATCH_UNREACHABLE";
@@ -94,7 +96,7 @@ export interface ConcurrentSharedWorldRoleResult {
         message: string;
     };
 }
-export interface ConcurrentSharedWorldLabResult {
+export interface ConcurrentSharedWorldLabResult extends AutomaticAnalysisResult {
     schema: typeof CONCURRENT_SHARED_WORLD_LAB_SCHEMA;
     ok: boolean;
     cwd: string;

package/dist/concurrent-shared-world-lab.js

@@ -32,6 +32,8 @@
 // synthetic-seeded-subjects ONLY. Verify fail-closes on subject.state.provenance != "seeded" and
 // requires the author attestation subject.exposure: synthetic. This is author-trust + a provenance
 // gate, NOT a no-real-data guarantee (Humanish cannot tell synthetic from real data).
+import { resolveAutomaticAnalysis } from "./automatic-analysis-config.js";
+import { completeAutomaticAnalysis, markFinalizedStudyResult } from "./automatic-analysis-completion.js";
 import { taskProtocolValidationReason } from "./lab-config.js";
 import { randomBytes } from "node:crypto";
 import { describeMissingKeys } from "./key-resolution.js";
@@ -500,7 +502,9 @@ function observerResultForConcurrentArtifacts(cwd, runId, artifactRoot, warnings
  * ticking into a directory something else is deleting, which surfaces as an unrelated ENOTEMPTY.
  */
 export async function runConcurrentSharedWorld(options) {
-    return withRunStatusScope(() => runConcurrentSharedWorldInScope(options));
+    const analysis = resolveAutomaticAnalysis(options.config.review?.analysis);
+    const result = await withRunStatusScope(() => runConcurrentSharedWorldInScope(options));
+    return completeAutomaticAnalysis(result, analysis.ok ? analysis.config : undefined, options.automaticAnalysis, options.config.review?.analysis === undefined ? "default" : "explicit");
 }
 async function runConcurrentSharedWorldInScope(options) {
     const { config, dryRun } = options;
@@ -530,6 +534,9 @@ async function runConcurrentSharedWorldInScope(options) {
         warnings: [],
         error: { code, message }
     });
+    const analysis = resolveAutomaticAnalysis(config.review?.analysis);
+    if (!analysis.ok)
+        return fail("HUMANISH_LAB_ANALYSIS_INVALID", analysis.message);
     const tasksReason = taskProtocolValidationReason(config, false);
     if (tasksReason)
         return fail("HUMANISH_LAB_TASKS_UNSUPPORTED", tasksReason);
@@ -1595,7 +1602,7 @@ async function runConcurrentSharedWorldInScope(options) {
         const passed = roleResults.filter((role) => role.ok).length;
         return { code: "HUMANISH_CONCURRENT_SHARED_WORLD_LAB_FAILED", message: `Concurrent shared-world run did not run coherently: ${passed}/${roles.length} actor(s) reached a terminal, engaged passed session.` };
     })();
-    return {
+    return markFinalizedStudyResult({
         schema: CONCURRENT_SHARED_WORLD_LAB_SCHEMA,
         ok,
         cwd,
@@ -1616,7 +1623,7 @@ async function runConcurrentSharedWorldInScope(options) {
         observer,
         warnings: [...warnings, ...adapterWarnings, ...observer.warnings],
         ...(errorResult === undefined ? {} : { error: errorResult })
-    };
+    }, runPaths);
 }
 /** Max windows live at the same instant (sweep over start/end points). The honest simultaneity
  *  count: lane COUNT says how many seats existed; this says how many ever ran at once. */