niceeval 0.13.3 → 0.13.4-canary.39

package/dist/experiment/host/cli/contribution.cjs

@@ -0,0 +1,835 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.experimentCliContributions = exports.SESSION_CLI_OPTIONS = exports.ACCEPT_CLI_OPTIONS = exports.DEBUG_CLI_OPTIONS = exports.EXP_TEARDOWN_CLI_OPTIONS = exports.EXP_RENAME_CLI_OPTIONS = exports.EXP_LIST_CLI_OPTIONS = exports.EXP_NORMAL_CLI_OPTIONS = exports.CHECK_CLI_OPTIONS = void 0;
+const effect_1 = require("effect");
+const application_ts_1 = require("../../../cli/application.cjs");
+const contribution_ts_1 = require("../../../cli/contribution.cjs");
+const project_configuration_ts_1 = require("../../../cli/project-configuration.cjs");
+const presentation_ts_1 = require("../../../record/host/cli/presentation.cjs");
+const index_ts_1 = require("../../../runner/feedback/index.cjs");
+const session_ts_1 = require("../../../runner/session.cjs");
+const aggregate_ts_1 = require("../../../shared/aggregate.cjs");
+const index_ts_2 = require("../../../i18n/index.cjs");
+const index_ts_3 = require("../index.cjs");
+const terminal_ts_1 = require("./terminal.cjs");
+const option = (type, summary, multiple) => Object.freeze({
+    type,
+    ...(multiple === undefined ? {} : { multiple }),
+    help: Object.freeze({ summary, visibility: "public" }),
+});
+const optionalTier = (summary, defaultValue, values, separated = false) => Object.freeze({
+    type: "boolean",
+    optionalValue: Object.freeze({
+        default: defaultValue,
+        ...(separated ? { separated: true } : {}),
+        values: Object.freeze([...values]),
+    }),
+    help: Object.freeze({ summary, visibility: "public" }),
+});
+const HELP_OPTION = Object.freeze({
+    type: "boolean",
+    short: "h",
+    help: Object.freeze({ summary: "Show command help.", visibility: "public" }),
+});
+exports.CHECK_CLI_OPTIONS = Object.freeze({
+    tag: option("string", "Select only Evals with this tag."),
+    help: HELP_OPTION,
+});
+exports.EXP_NORMAL_CLI_OPTIONS = Object.freeze({
+    attempts: option("string", "Run each selected Eval this many times."),
+    "max-concurrency": option("string", "Limit concurrent Attempt execution."),
+    "max-build-concurrency": option("string", "Limit concurrent Sandbox build preparation."),
+    timeout: option("string", "Set the per-Attempt timeout in milliseconds."),
+    budget: option("string", "Set the Invocation budget in USD."),
+    tag: option("string", "Select only Evals with this tag."),
+    junit: option("string", "Write a required JUnit report."),
+    json: option("boolean", "Write the command's machine document or event stream."),
+    dry: option("boolean", "Plan without creating an Invocation."),
+    rerun: optionalTier("Require failed or all targets to run again.", "failed", ["failed", "all"], true),
+    "keep-sandbox": optionalTier("Keep failed or all finished Sandboxes.", "failed", ["failed", "all"]),
+    "early-exit": option("boolean", "Stop remaining attempts after a passing result."),
+    "no-early-exit": option("boolean", "Force all configured attempts to run."),
+    record: option("string", "Use this Record root."),
+    help: HELP_OPTION,
+});
+exports.EXP_LIST_CLI_OPTIONS = Object.freeze({
+    tag: option("string", "Select only Evals with this tag."),
+    json: option("boolean", "Write the catalog machine document."),
+    help: HELP_OPTION,
+});
+exports.EXP_RENAME_CLI_OPTIONS = Object.freeze({
+    dry: option("boolean", "Preview the explicit Experiment rename."),
+    json: option("boolean", "Write the rename machine document."),
+    help: HELP_OPTION,
+});
+exports.EXP_TEARDOWN_CLI_OPTIONS = Object.freeze({
+    teardown: option("boolean", "Run explicit Experiment teardown recovery."),
+    json: option("boolean", "Write machine output where the operation supports it."),
+    "recover-shared-state": option("string", "Name a shared-state key for explicit recovery."),
+    "owner-token": option("string", "Provide the exact shared-state owner token."),
+    "confirm-owner-terminated": option("boolean", "Confirm the recorded owner has terminated."),
+    "confirm-remote-quiesced": option("boolean", "Confirm remote shared state is quiesced."),
+    help: HELP_OPTION,
+});
+exports.DEBUG_CLI_OPTIONS = Object.freeze({
+    json: option("boolean", "Write the command-plan machine document."),
+    help: HELP_OPTION,
+});
+exports.ACCEPT_CLI_OPTIONS = Object.freeze({
+    record: option("string", "Use this Record root."),
+    help: HELP_OPTION,
+});
+exports.SESSION_CLI_OPTIONS = Object.freeze({
+    all: option("boolean", "Include completed invocation status entries."),
+    json: option("boolean", "Write the status machine document."),
+    help: HELP_OPTION,
+});
+/** `exp` is a command family; its composition schema is its own frozen union. */
+const EXP_CLI_OPTIONS = Object.freeze({
+    ...exports.EXP_NORMAL_CLI_OPTIONS,
+    ...exports.EXP_LIST_CLI_OPTIONS,
+    ...exports.EXP_RENAME_CLI_OPTIONS,
+    ...exports.EXP_TEARDOWN_CLI_OPTIONS,
+});
+const SHARED_STATE_RECOVERY_USAGE = `  niceeval exp <selector> --teardown --recover-shared-state <key>
+    --owner-token <token> --confirm-owner-terminated --confirm-remote-quiesced`;
+const CHECK_HELP = `Check Experiment selection:
+  niceeval check [<experiment-prefix> [<eval-prefix>...]] [--tag <tag>]
+
+Options:
+  --tag <tag>  select only Evals with this tag
+  -h, --help   show this help
+`;
+const EXP_HELP = `Run and maintain Experiments:
+  niceeval exp [<experiment-prefix> [<eval-prefix>...]] [options]
+  niceeval exp list [<experiment-prefix>] [--tag <tag>] [--json]
+  niceeval exp rename <old-id> <new-id> [--dry] [--json]
+${SHARED_STATE_RECOVERY_USAGE}
+
+Run options:
+  --attempts <n>                 run each selected Eval this many times
+  --max-concurrency <n>          limit concurrent Attempt execution
+  --max-build-concurrency <n>    limit concurrent Sandbox build preparation
+  --timeout <ms>                 set the per-Attempt timeout
+  --budget <usd>                 set the Invocation budget
+  --tag <tag>                    select only Evals with this tag
+  --rerun[=failed|all]           require selected targets to run again
+  --keep-sandbox[=failed|all]    retain selected finished Sandboxes
+  --early-exit / --no-early-exit
+  --dry                          plan without creating an Invocation
+  --json                         write machine output or the Invocation event stream
+  --junit <path>                 write a required JUnit report
+  --record <root>                use this Record root
+
+Recovery options:
+  --teardown                     run only explicit Experiment teardown recovery
+  --recover-shared-state <key>   inspect or recover this immutable shared-state owner
+  --owner-token <token>          provide the exact owner token shown by inspection
+  --confirm-owner-terminated     confirm the recorded owner has terminated
+  --confirm-remote-quiesced      confirm remote shared state is quiesced
+  -h, --help                     show this help
+`;
+const DEBUG_HELP = `Inspect one Experiment lifecycle plan:
+  niceeval debug <experiment-selector> <eval-selector> [--json]
+
+Options:
+  --json       write the command-plan machine document
+  -h, --help  show this help
+`;
+const ACCEPT_HELP = `Accept exact historical Attempt locators:
+  niceeval accept @<locator>... [--record <root>]
+
+Options:
+  --record <root>  use this Record root
+  -h, --help       show this help
+`;
+const SESSION_HELP = `Inspect project-local ephemeral Invocation status:
+  niceeval session list [--all] [<experiment-prefix>]
+  niceeval session show <invocation-id>
+
+Options:
+  --all        include completed Invocation status entries
+  --json       write the status machine document
+  -h, --help  show this help
+`;
+const EXP_COMMAND_SUMMARY = `list, plan, run, rename, or recover Experiments
+      explicit sharedState recovery:
+${SHARED_STATE_RECOVERY_USAGE}`;
+function failure(operation, cause, exitCode = 1, display) {
+    return new contribution_ts_1.CliFeatureError({
+        feature: "experiments",
+        operation,
+        cause,
+        exitCode,
+        ...(display === undefined ? {} : { display }),
+    });
+}
+function write(channel, text) {
+    return effect_1.Effect.flatMap(application_ts_1.CliOutput, (output) => channel === "stdout" ? output.writeStdout(text) : output.writeStderr(text)).pipe(effect_1.Effect.mapError((cause) => failure(`write ${channel}`, cause)));
+}
+function numberFlag(value, name, positive = false) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !/^[0-9]+(?:\.[0-9]+)?$/u.test(value))
+        throw new Error(`${name} requires a number.`);
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed < 0 || (positive && (!Number.isInteger(parsed) || parsed === 0))) {
+        throw new Error(positive ? `${name} requires a positive integer.` : `${name} requires a non-negative finite number.`);
+    }
+    return parsed;
+}
+function enumFlag(value, name, values) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string" || !values.includes(value))
+        throw new Error(`${name} accepts ${values.join(" or ")}.`);
+    return value;
+}
+function jsonDocument(value) {
+    return `${JSON.stringify(value)}\n`;
+}
+function catalogText(catalog) {
+    return catalog.experiments.map((experiment) => [
+        experiment.id,
+        experiment.description ?? "—",
+        experiment.agent,
+        experiment.model ?? "—",
+        `attempts=${experiment.attempts}`,
+        `evals=${experiment.evalIds.length}`,
+        `labels=${JSON.stringify(experiment.labels)}`,
+    ].join("\t")).join("\n") + (catalog.experiments.length === 0 ? "" : "\n");
+}
+function catalogJson(catalog) {
+    return jsonDocument({
+        format: "niceeval.experiments",
+        schemaVersion: 1,
+        experiments: catalog.experiments.map((experiment) => ({
+            experimentId: experiment.id,
+            ...(experiment.description === undefined ? {} : { description: experiment.description }),
+            agent: experiment.agent,
+            ...(experiment.model === undefined ? {} : { model: experiment.model }),
+            attempts: experiment.attempts,
+            evalCount: experiment.evalIds.length,
+            labels: experiment.labels,
+            selectedEvalIds: experiment.evalIds,
+        })),
+    });
+}
+function checkText(result) {
+    return result.status === "linked"
+        ? `Sandbox layers linked: ${result.pairCount} pair${result.pairCount === 1 ? "" : "s"}.\n`
+        : `Experiment selection: ${result.status}.\n`;
+}
+function selectionProblemText(result) {
+    if (result.status === "experiment-no-match") {
+        return (0, index_ts_2.t)("cli.experiment.noMatch", {
+            arg: result.selector ?? (0, index_ts_2.t)("cli.all"),
+            experiments: (0, aggregate_ts_1.browsableExperimentPaths)(result.candidates ?? []).join(", ") || (0, index_ts_2.t)("cli.none"),
+        });
+    }
+    if (result.status === "eval-no-match") {
+        return (0, index_ts_2.t)("cli.experiment.noEvalPrefixMatch", {
+            pattern: result.selector ?? "",
+            selection: (result.experimentIds ?? []).join(", ") || (0, index_ts_2.t)("cli.all"),
+        });
+    }
+    return (0, index_ts_2.t)("cli.experiment.noEvalsSelected", {
+        selection: (result.experimentIds ?? []).join(", ") || (0, index_ts_2.t)("cli.all"),
+        experiments: (0, aggregate_ts_1.browsableExperimentPaths)(result.candidates ?? result.experimentIds ?? []).join(", ") || (0, index_ts_2.t)("cli.none"),
+    });
+}
+function acceptText(results) {
+    return results.map((result) => (0, index_ts_2.t)("cli.accept.done", {
+        runId: result.runId,
+        sourceLocator: result.sourceLocator,
+        locator: result.locator,
+        fingerprint: result.fingerprint,
+    })).join("");
+}
+function sharedStateEvidenceText(evidence) {
+    return (0, index_ts_2.t)("cli.exp.sharedStateRecoveryTarget", {
+        key: evidence.key,
+        experimentId: evidence.experimentId,
+        ownerToken: evidence.ownerToken,
+        host: evidence.host,
+        pid: evidence.pid,
+        processIdentity: evidence.processIdentity,
+        heartbeatAt: evidence.heartbeatAt,
+    });
+}
+function teardownInspectionEvidence(inspection) {
+    return "evidence" in inspection ? inspection.evidence : undefined;
+}
+function teardownInspectionProblemText(inspection) {
+    switch (inspection.status) {
+        case "no-evidence":
+            return `No recoverable sharedState ownership evidence exists for ${JSON.stringify(inspection.key)}.\n`;
+        case "selection-not-unique":
+            return "sharedState recovery requires an experiment selector that resolves to exactly one Experiment.\n";
+        case "experiment-mismatch":
+            return `sharedState key ${JSON.stringify(inspection.evidence.key)} belongs to experiment ${inspection.evidence.experimentId}, not ${inspection.selectedExperimentId}; refusing recovery.\n`;
+        case "teardown-required":
+            return (0, index_ts_2.t)("cli.exp.sharedStateRecoveryTeardownRequired", { experimentId: inspection.experimentId });
+        case "recovery-confirmation-required":
+            return (0, index_ts_2.t)("cli.exp.sharedStateRecoveryFlags");
+        default:
+            return undefined;
+    }
+}
+function teardownFailure(operation, cause, recoveryKey) {
+    const code = typeof cause === "object" && cause !== null && typeof Reflect.get(cause, "code") === "string"
+        ? String(Reflect.get(cause, "code"))
+        : undefined;
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const display = code === "shared-state-recovery-registration-failed" && recoveryKey !== undefined
+        ? (0, index_ts_2.t)("cli.exp.sharedStateRecoveryRegistrationFailed", { key: recoveryKey, message })
+        : code === "shared-state-recovery-already-released-registration-failed" && recoveryKey !== undefined
+            ? (0, index_ts_2.t)("cli.exp.sharedStateRecoveryAlreadyReleasedRegistrationFailed", { key: recoveryKey, message })
+            : code === "shared-state-recovery-completion-failed"
+                ? `sharedState recovery could not release its exact owner token: ${message}\n`
+                : recoveryKey === undefined
+                    ? undefined
+                    : `sharedState recovery refused: ${message}\n`;
+    return failure(operation, cause, 1, display);
+}
+function invocationText(result) {
+    return `Invocation ${result.receipt.invocationId} · ${result.receipt.completion}\nRuns: ${result.receipt.runIds.join(", ") || "none"}\nResults: ${result.summary.passed} passed · ${result.summary.failed} failed · ${result.summary.errored} errored · ${result.summary.skipped} skipped\n`;
+}
+function dryRows(plan) {
+    const rows = new Map();
+    for (const slot of plan.slots) {
+        const key = JSON.stringify([slot.target.experimentId, slot.target.evalId]);
+        const row = rows.get(key) ?? {
+            experimentId: slot.target.experimentId,
+            evalId: slot.target.evalId,
+            ...(slot.target.evalGroupId === undefined ? {} : { evalGroupId: slot.target.evalGroupId, evalGroupIndex: slot.target.evalGroupIndex }),
+            slots: [],
+            readbacks: [],
+        };
+        row.slots.push({
+            ...slot.target,
+            state: slot.state === "reuse" ? "reused" : "gap",
+            comparisons: slot.comparisons,
+            ...(slot.state === "gap" ? { reason: slot.reason, scope: slot.scope } : {}),
+        });
+        if (plan.lockedPairs.includes(key))
+            row.locked = true;
+        rows.set(key, row);
+    }
+    for (const readback of plan.readbacks) {
+        const key = JSON.stringify([readback.target.experimentId, readback.target.evalId]);
+        const row = rows.get(key) ?? { experimentId: readback.target.experimentId, evalId: readback.target.evalId, slots: [], readbacks: [] };
+        row.readbacks.push(readback);
+        if (plan.lockedPairs.includes(key))
+            row.locked = true;
+        rows.set(key, row);
+    }
+    return [...rows.values()].map((row) => ({
+        ...row,
+        slots: [...row.slots].sort((left, right) => left.attempt - right.attempt),
+        readbacks: [...row.readbacks].sort((left, right) => left.target.attempt - right.target.attempt),
+    })).sort((left, right) => left.experimentId.localeCompare(right.experimentId) || left.evalId.localeCompare(right.evalId));
+}
+function dryText(plan, shape, pluginCount) {
+    const rows = dryRows(plan);
+    const reused = plan.slots.filter((slot) => slot.state === "reuse").length;
+    const lines = [
+        `plan: ${shape.totalAttempts} attempts · ${shape.evals} evals × ${shape.configurations} configs · runs ${shape.attempts}`,
+        ...(reused === 0 ? [] : [`reuse: ${reused}/${shape.totalAttempts} exact current Record attempts`]),
+        `plugins: ${pluginCount} lifecycle occurrences`,
+    ];
+    for (const row of rows) {
+        const slots = row.slots;
+        const reusedAttempts = slots.filter((slot) => slot.state === "reused").map((slot) => slot.attempt);
+        const gaps = slots.filter((slot) => slot.state === "gap");
+        const parts = [
+            ...(row.locked ? ["locked"] : []),
+            ...(reusedAttempts.length === 0 ? [] : [`reused ${reusedAttempts.join(",")}`]),
+            ...gaps.map((slot) => `gap ${slot.attempt}:${slot.reason ?? "unknown"}`),
+        ];
+        lines.push(`${row.experimentId}  ${row.evalId}  ${parts.join(" · ") || "no slots"}`);
+        const hasIdentityGap = gaps.some((slot) => slot.reason === "identity-mismatch");
+        for (const readback of row.readbacks) {
+            const verdict = readback.state === "reused"
+                ? readback.verdict
+                : readback.verdict.state === "available"
+                    ? readback.verdict.value
+                    : readback.verdict.state;
+            lines.push(`  source ${readback.source.locator} · ${readback.state} · verdict ${verdict}`);
+            if (hasIdentityGap && readback.state === "prior")
+                lines.push(`  accept: niceeval accept ${readback.source.locator}`);
+        }
+    }
+    return `${lines.join("\n")}\n`;
+}
+function dryJson(plan, shape, plugins) {
+    return jsonDocument({
+        format: "niceeval.current-reuse-plan/v1",
+        schemaVersion: 1,
+        total: shape.totalAttempts,
+        evals: shape.evals,
+        configs: shape.configurations,
+        attempts: shape.attempts,
+        reused: plan.slots.filter((slot) => slot.state === "reuse").length,
+        matrix: dryRows(plan),
+        plugins,
+    });
+}
+const RENAME_REASON_MESSAGE = {
+    "source-empty": "cli.rename.error.sourceEmpty",
+    "target-not-found": "cli.rename.error.targetNotFound",
+    "target-has-results": "cli.rename.error.targetHasResults",
+    "source-unreadable": "cli.rename.error.sourceUnreadable",
+    "artifact-unavailable": "cli.rename.error.artifactUnavailable",
+    "nothing-to-migrate": "cli.rename.error.nothingToMigrate",
+};
+function renameText(result) {
+    if (result.status === "done") {
+        const lines = [
+            (0, index_ts_2.t)("cli.rename.doneHeader", { oldId: result.oldId, newId: result.newId, count: result.migrated.length }),
+            (0, index_ts_2.t)("cli.rename.snapshotPath", { path: result.snapshotPath }),
+            ...result.migrated.map((entry) => (0, index_ts_2.t)("cli.rename.doneRow", {
+                evalId: entry.evalId,
+                sourceLocator: entry.sourceLocator,
+                locator: entry.locator,
+            })),
+        ];
+        return `${lines.join("\n")}\n`;
+    }
+    if (result.status === "rejected") {
+        const lines = [(0, index_ts_2.t)(RENAME_REASON_MESSAGE[result.reason], {
+                oldId: result.oldId,
+                newId: result.newId,
+                evalId: result.evalId ?? "",
+            })];
+        if ((result.conflictingEvals?.length ?? 0) > 0) {
+            lines.push((0, index_ts_2.t)("cli.rename.conflicting", { evals: result.conflictingEvals.join(", ") }));
+        }
+        return `${lines.join("\n")}\n`;
+    }
+    const lines = [(0, index_ts_2.t)("cli.rename.previewHeader", { oldId: result.oldId, newId: result.newId })];
+    if (result.blocked !== undefined) {
+        lines.push((0, index_ts_2.t)("cli.rename.blocked", { reason: result.blocked.reason }));
+        lines.push(...(result.blocked.conflictingEvals ?? []).map((evalId) => `  ${evalId}`));
+        if (result.blocked.detail !== undefined)
+            lines.push(`  ${result.blocked.detail}`);
+    }
+    if (result.migrations.length > 0) {
+        lines.push((0, index_ts_2.t)("cli.rename.migratingHeader", { count: result.migrations.length }));
+        lines.push(...result.migrations.map((entry) => (0, index_ts_2.t)("cli.rename.migratingRow", {
+            evalId: entry.evalId,
+            sourceLocator: entry.sourceLocator,
+            newId: result.newId,
+        })));
+    }
+    if (result.excluded.length > 0) {
+        lines.push((0, index_ts_2.t)("cli.rename.excludedHeader", { count: result.excluded.length }));
+        lines.push(...result.excluded.map((entry) => (0, index_ts_2.t)("cli.rename.excludedRow", { evalId: entry.evalId, reason: entry.reason })));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function renameJson(result) {
+    return jsonDocument({ format: "niceeval.experimentRename", schemaVersion: 1, ...result });
+}
+function parsed(argv, options) {
+    return effect_1.Effect.flatMap(application_ts_1.CliArguments, (argumentsService) => effect_1.Effect.try({
+        try: () => argumentsService.parse(argv, options),
+        catch: (cause) => failure("parse command", cause),
+    }));
+}
+function factsAndConfig() {
+    return effect_1.Effect.gen(function* () {
+        const facts = yield* application_ts_1.CliInvocationFacts;
+        const invocation = yield* facts.facts.pipe(effect_1.Effect.mapError((cause) => failure("read invocation facts", cause)));
+        const project = yield* project_configuration_ts_1.ProjectConfiguration;
+        const config = yield* project.load(invocation.cwd).pipe(effect_1.Effect.mapError((cause) => failure("load config", cause)));
+        return Object.freeze({ invocation, config });
+    });
+}
+function selection(positionals) {
+    const [experimentSelector, ...evalSelectors] = positionals;
+    return Object.freeze({
+        ...(experimentSelector === undefined ? {} : { experimentSelector }),
+        ...(evalSelectors.length === 0 ? {} : { evalSelectors: Object.freeze(evalSelectors) }),
+    });
+}
+function overrides(values) {
+    const attempts = numberFlag(values.attempts, "--attempts", true);
+    const timeoutMs = numberFlag(values.timeout, "--timeout");
+    const budget = numberFlag(values.budget, "--budget");
+    const maxConcurrency = numberFlag(values["max-concurrency"], "--max-concurrency", true);
+    const maxBuildConcurrency = numberFlag(values["max-build-concurrency"], "--max-build-concurrency", true);
+    const rerun = enumFlag(values.rerun, "--rerun", ["failed", "all"]);
+    const keepSandbox = enumFlag(values["keep-sandbox"], "--keep-sandbox", ["failed", "all"]);
+    return Object.freeze({
+        ...(attempts === undefined ? {} : { attempts }),
+        ...(timeoutMs === undefined ? {} : { timeoutMs }),
+        ...(budget === undefined ? {} : { budget }),
+        ...(maxConcurrency === undefined ? {} : { maxConcurrency }),
+        ...(maxBuildConcurrency === undefined ? {} : { maxBuildConcurrency }),
+        ...(rerun === undefined ? {} : { rerun: rerun }),
+        ...(keepSandbox === undefined ? {} : { keepSandbox: keepSandbox }),
+        ...(values["no-early-exit"] === true ? { earlyExit: false } : values["early-exit"] === true ? { earlyExit: true } : {}),
+    });
+}
+const checkCommand = Object.freeze({
+    name: "check",
+    summary: "check Experiment and Sandbox selection",
+    options: exports.CHECK_CLI_OPTIONS,
+    run: (argv) => effect_1.Effect.gen(function* () {
+        const input = yield* parsed(argv, exports.CHECK_CLI_OPTIONS);
+        if (input.values.help === true)
+            return yield* write("stdout", CHECK_HELP).pipe(effect_1.Effect.as(0));
+        const { invocation, config } = yield* factsAndConfig();
+        const result = yield* index_ts_3.experimentHost.check({ cwd: invocation.cwd, config, ...selection(input.positionals) }).pipe(effect_1.Effect.mapError((cause) => failure("check", cause)));
+        if (result.status !== "linked") {
+            yield* write("stderr", selectionProblemText(result));
+            return 1;
+        }
+        yield* write("stdout", checkText(result));
+        return 0;
+    }),
+});
+const expCommand = Object.freeze({
+    name: "exp",
+    summary: EXP_COMMAND_SUMMARY,
+    options: EXP_CLI_OPTIONS,
+    run: (argv) => effect_1.Effect.gen(function* () {
+        // First parse only determines the family branch. The second, branch-owned
+        // schema rejects irrelevant flags before facts, config, or .env are read.
+        const preliminary = yield* parsed(argv, EXP_CLI_OPTIONS);
+        const teardownMode = preliminary.values.teardown === true;
+        const preliminaryVerb = preliminary.positionals[0];
+        if (preliminaryVerb === "help" && preliminary.positionals.length === 1) {
+            return yield* write("stdout", EXP_HELP).pipe(effect_1.Effect.as(0));
+        }
+        const input = yield* parsed(argv, teardownMode
+            ? exports.EXP_TEARDOWN_CLI_OPTIONS
+            : preliminaryVerb === "list"
+                ? exports.EXP_LIST_CLI_OPTIONS
+                : preliminaryVerb === "rename"
+                    ? exports.EXP_RENAME_CLI_OPTIONS
+                    : exports.EXP_NORMAL_CLI_OPTIONS);
+        if (input.values.help === true)
+            return yield* write("stdout", EXP_HELP).pipe(effect_1.Effect.as(0));
+        const [verb, ...rest] = input.positionals;
+        const facts = yield* application_ts_1.CliInvocationFacts;
+        const invocation = yield* facts.facts.pipe(effect_1.Effect.mapError((cause) => failure("read invocation facts", cause)));
+        if (teardownMode) {
+            const project = yield* project_configuration_ts_1.ProjectConfiguration;
+            yield* project.load(invocation.cwd).pipe(effect_1.Effect.mapError((cause) => failure("load config", cause)));
+            if (typeof input.values["recover-shared-state"] === "string" && input.values.json === true) {
+                yield* write("stderr", (0, index_ts_2.t)("cli.exp.sharedStateRecoveryJsonUnsupported"));
+                return 1;
+            }
+            if (input.positionals.length > 1) {
+                return yield* write("stderr", "niceeval exp --teardown accepts at most one Experiment selector.\n").pipe(effect_1.Effect.as(1));
+            }
+            const selector = input.positionals[0];
+            const recoveryKey = typeof input.values["recover-shared-state"] === "string"
+                ? input.values["recover-shared-state"]
+                : undefined;
+            const inspection = yield* index_ts_3.experimentHost.teardown.inspect({
+                cwd: invocation.cwd,
+                currentHost: invocation.hostname,
+                ...(selector === undefined ? {} : { experimentSelector: selector }),
+                ...(recoveryKey === undefined ? {} : { recoveryKey }),
+            }).pipe(effect_1.Effect.mapError((cause) => failure("inspect teardown", cause)));
+            if (inspection.status === "experiment-no-match" || inspection.status === "eval-no-match" || inspection.status === "empty-selection") {
+                yield* write("stderr", selectionProblemText(inspection));
+                return 1;
+            }
+            const evidence = teardownInspectionEvidence(inspection);
+            if (evidence !== undefined)
+                yield* write("stderr", sharedStateEvidenceText(evidence));
+            if (inspection.status === "no-evidence" ||
+                inspection.status === "selection-not-unique" ||
+                inspection.status === "experiment-mismatch") {
+                yield* write("stderr", teardownInspectionProblemText(inspection));
+                return 1;
+            }
+            // Recovery evidence is deliberately available before confirmations.  This
+            // preserves the after-kill operator flow while keeping the normal
+            // teardown path free of Record migration and Invocation construction.
+            if (recoveryKey !== undefined && (typeof input.values["owner-token"] !== "string" ||
+                input.values["confirm-owner-terminated"] !== true ||
+                input.values["confirm-remote-quiesced"] !== true)) {
+                yield* write("stderr", (0, index_ts_2.t)("cli.exp.sharedStateRecoveryFlags"));
+                return 1;
+            }
+            if (inspection.status === "teardown-required") {
+                yield* write("stderr", teardownInspectionProblemText(inspection));
+                return 1;
+            }
+            const interruption = yield* application_ts_1.CliInterruption;
+            const output = yield* application_ts_1.CliOutput;
+            const result = yield* index_ts_3.experimentHost.teardown.run({
+                cwd: invocation.cwd,
+                currentHost: invocation.hostname,
+                ...(selector === undefined ? {} : { experimentSelector: selector }),
+                ...(recoveryKey === undefined ? {} : { recoveryKey }),
+                ...(typeof input.values["owner-token"] === "string" ? { ownerToken: input.values["owner-token"] } : {}),
+                ...(input.values["confirm-owner-terminated"] === true ? { confirmOwnerTerminated: true } : {}),
+                ...(input.values["confirm-remote-quiesced"] === true ? { confirmRemoteQuiesced: true } : {}),
+                signal: interruption.invocationSignal,
+                observer: Object.freeze({
+                    observe(event) {
+                        if (event.type === "diagnostic")
+                            output.writeStderrSync(`${event.message}\n`);
+                    },
+                }),
+            }).pipe(effect_1.Effect.mapError((cause) => teardownFailure("run teardown", cause, recoveryKey)));
+            if (result.status === "completed") {
+                for (const experiment of result.experiments) {
+                    if (experiment.outcome === "succeeded") {
+                        yield* write("stderr", (0, index_ts_2.t)("cli.exp.teardownDone", { experimentId: experiment.experimentId }));
+                    }
+                    else if (experiment.outcome === "failed") {
+                        yield* write("stderr", (0, index_ts_2.t)("cli.exp.teardownFailed", {
+                            experimentId: experiment.experimentId,
+                            message: experiment.error ?? "unknown",
+                        }));
+                    }
+                }
+            }
+            else if (result.status === "recovered" || result.status === "already-released") {
+                if (result.status === "recovered") {
+                    yield* write("stderr", (0, index_ts_2.t)("cli.exp.teardownDone", { experimentId: result.experimentId }));
+                }
+                if (result.status === "already-released")
+                    yield* write("stderr", (0, index_ts_2.t)("cli.exp.sharedStateRecoveryAlreadyReleased", { key: result.key }));
+                yield* write("stderr", (0, index_ts_2.t)("runner.sharedStateExplicitRecovered", {
+                    key: result.key,
+                    experimentId: result.experimentId,
+                    ownerToken: result.ownerToken,
+                }));
+            }
+            else if (result.status === "recovery-teardown-failed") {
+                yield* write("stderr", (0, index_ts_2.t)("cli.exp.teardownFailed", {
+                    experimentId: result.evidence.experimentId,
+                    message: result.error,
+                }));
+            }
+            else {
+                const changedEvidence = teardownInspectionEvidence(result);
+                if (changedEvidence !== undefined)
+                    yield* write("stderr", sharedStateEvidenceText(changedEvidence));
+                const problem = teardownInspectionProblemText(result);
+                if (problem !== undefined)
+                    yield* write("stderr", problem);
+            }
+            return result.status === "completed" || result.status === "recovered" || result.status === "already-released" ? 0 : 1;
+        }
+        if (verb === "list") {
+            if (rest.length > 1)
+                return yield* write("stderr", "niceeval exp list accepts at most one experiment prefix.\n").pipe(effect_1.Effect.as(1));
+            const project = yield* project_configuration_ts_1.ProjectConfiguration;
+            yield* project.load(invocation.cwd).pipe(effect_1.Effect.mapError((cause) => failure("load config", cause)));
+            const result = yield* index_ts_3.experimentHost.catalog({ cwd: invocation.cwd, ...selection(rest), ...(typeof input.values.tag === "string" ? { tag: input.values.tag } : {}) }).pipe(effect_1.Effect.mapError((cause) => failure("list", cause)));
+            if (result.experiments.length === 0 && rest[0] !== undefined) {
+                yield* write("stderr", (0, index_ts_2.t)("cli.experiment.noMatch", {
+                    arg: rest[0],
+                    experiments: (0, aggregate_ts_1.browsableExperimentPaths)(result.experimentIds).join(", ") || (0, index_ts_2.t)("cli.none"),
+                }));
+                return 1;
+            }
+            yield* write("stdout", input.values.json === true ? catalogJson(result) : catalogText(result));
+            return 0;
+        }
+        if (verb === "rename") {
+            const [oldId, newId] = rest;
+            if (oldId === undefined || newId === undefined || rest.length !== 2)
+                return yield* write("stderr", "usage: niceeval exp rename <old-id> <new-id>\n").pipe(effect_1.Effect.as(1));
+            const renameInput = { cwd: invocation.cwd, oldId, newId };
+            const result = input.values.dry === true
+                ? yield* index_ts_3.experimentHost.rename.plan(renameInput).pipe(effect_1.Effect.mapError((cause) => failure("plan rename", cause)))
+                : yield* index_ts_3.experimentHost.rename.apply(renameInput).pipe(effect_1.Effect.mapError((cause) => failure("rename", cause)));
+            yield* write("stdout", input.values.json === true ? renameJson(result) : renameText(result));
+            return result.status === "rejected" || (result.status === "plan" && result.blocked !== undefined) ? 1 : 0;
+        }
+        const project = yield* project_configuration_ts_1.ProjectConfiguration;
+        const config = yield* project.load(invocation.cwd).pipe(effect_1.Effect.mapError((cause) => failure("load config", cause)));
+        const plan = yield* index_ts_3.experimentHost.invocation.plan({
+            cwd: invocation.cwd,
+            config,
+            ...selection(input.positionals),
+            ...(typeof input.values.tag === "string" ? { tag: input.values.tag } : {}),
+            ...(typeof input.values.record === "string" ? { recordRoot: input.values.record } : {}),
+            overrides: overrides(input.values),
+            preview: input.values.dry === true,
+        }).pipe(effect_1.Effect.mapError((cause) => failure("plan invocation", cause, 1, (0, presentation_ts_1.renderAutomaticMigrationFailure)(cause))));
+        const migrationNotice = (0, presentation_ts_1.renderAutomaticMigrationResult)(plan.automaticMigration);
+        if (migrationNotice !== undefined)
+            yield* write("stderr", migrationNotice);
+        if (plan.status !== "ready") {
+            yield* write("stderr", selectionProblemText(plan));
+            return 1;
+        }
+        if (input.values.dry === true) {
+            if (plan.dry === undefined)
+                return yield* effect_1.Effect.fail(failure("preview invocation", new Error("Experiment Host did not return the requested dry plan.")));
+            yield* write("stdout", input.values.json === true
+                ? dryJson(plan.dry, plan.shape, plan.pluginAudit.occurrences)
+                : dryText(plan.dry, plan.shape, plan.pluginAudit.occurrences.length));
+            return 0;
+        }
+        const interruption = yield* application_ts_1.CliInterruption;
+        if (!(yield* effect_1.Effect.sync(interruption.enterGracefulDispatch)))
+            return yield* effect_1.Effect.interrupt;
+        const terminal = yield* terminal_ts_1.ExperimentCliTerminal;
+        const profile = (0, index_ts_1.resolveOutputForm)({
+            json: input.values.json === true,
+            isTTY: invocation.stderr.isTTY,
+        });
+        const renderer = profile === "human"
+            ? (0, index_ts_1.createHumanRenderer)({
+                io: terminal.feedback,
+                command: ["niceeval", "exp", ...input.positionals].join(" ").trim(),
+            })
+            : (0, index_ts_1.createJsonRenderer)({ io: terminal.feedback });
+        const coordinator = (0, index_ts_1.createFeedbackCoordinator)({
+            profile,
+            renderer,
+            io: terminal.feedback,
+            // Experiment Host installs one lossless multiplexing sink for feedback
+            // and the project-local Session observer.
+            activateSink: false,
+        });
+        const outcome = yield* effect_1.Effect.either(effect_1.Effect.scoped(effect_1.Effect.gen(function* () {
+            yield* effect_1.Effect.acquireRelease(effect_1.Effect.sync(() => (0, index_ts_1.createInputGuard)({
+                stdin: terminal.stdin,
+                stderrIsTTY: terminal.feedback.stderr.isTTY,
+                coordinator,
+                onInterrupt: interruption.requestInterrupt,
+            })), (guard) => effect_1.Effect.sync(guard.stop));
+            return yield* index_ts_3.experimentHost.invocation.run({
+                plan: plan.plan,
+                signal: interruption.invocationSignal,
+                feedback: Object.freeze({ coordinator }),
+                ...(typeof input.values.junit === "string" ? { junitPath: input.values.junit } : {}),
+            });
+        })));
+        if (effect_1.Either.isLeft(outcome)) {
+            if (outcome.left.code === "runner-record-assertions-invalid") {
+                yield* write("stderr", `error: ${outcome.left.message}\n`);
+                return 1;
+            }
+            return yield* effect_1.Effect.fail(failure("run invocation", outcome.left));
+        }
+        const result = outcome.right;
+        if (result.exitCode === undefined) {
+            return yield* effect_1.Effect.fail(failure("finish invocation feedback", new Error("Experiment Host returned without the requested presentation exit fold.")));
+        }
+        return result.exitCode;
+    }),
+});
+const debugCommand = Object.freeze({
+    name: "debug",
+    summary: "show one Experiment lifecycle plan",
+    options: exports.DEBUG_CLI_OPTIONS,
+    run: (argv) => effect_1.Effect.gen(function* () {
+        const input = yield* parsed(argv, exports.DEBUG_CLI_OPTIONS);
+        if (input.values.help === true)
+            return yield* write("stdout", DEBUG_HELP).pipe(effect_1.Effect.as(0));
+        const [experimentSelector, evalSelector] = input.positionals;
+        if (experimentSelector === undefined || evalSelector === undefined || input.positionals.length !== 2) {
+            return yield* write("stderr", (0, index_ts_2.t)("cli.debug.usage")).pipe(effect_1.Effect.as(1));
+        }
+        const { invocation, config } = yield* factsAndConfig();
+        const result = yield* index_ts_3.experimentHost.debug({ cwd: invocation.cwd, config, experimentSelector, evalSelector }).pipe(effect_1.Effect.mapError((cause) => failure("debug", cause)));
+        switch (result.status) {
+            case "experiment-no-match":
+                yield* write("stderr", (0, index_ts_2.t)("cli.debug.experimentNoMatch", {
+                    selector: result.selector,
+                    candidates: result.candidates.join(", ") || (0, index_ts_2.t)("cli.none"),
+                }));
+                return 1;
+            case "experiment-ambiguous":
+                yield* write("stderr", (0, index_ts_2.t)("cli.debug.experimentAmbiguous", {
+                    selector: result.selector,
+                    candidates: result.candidates.join(", "),
+                }));
+                return 1;
+            case "eval-no-match":
+                yield* write("stderr", (0, index_ts_2.t)("cli.debug.evalNoMatch", {
+                    selector: result.selector,
+                    experimentId: result.experimentId,
+                    candidates: result.candidates.join(", ") || (0, index_ts_2.t)("cli.none"),
+                }));
+                return 1;
+            case "eval-ambiguous":
+                yield* write("stderr", (0, index_ts_2.t)("cli.debug.evalAmbiguous", {
+                    selector: result.selector,
+                    experimentId: result.experimentId,
+                    candidates: result.candidates.join(", "),
+                }));
+                return 1;
+            case "planned":
+                yield* write("stdout", input.values.json === true
+                    ? jsonDocument({
+                        format: "niceeval.debug-plan/v1",
+                        schemaVersion: 1,
+                        experimentId: result.experimentId,
+                        evalId: result.evalId,
+                        commandPlan: result.commandPlan,
+                    })
+                    : (0, index_ts_1.renderHumanCommandPlan)(result.commandPlan, {
+                        isTTY: invocation.stdout.isTTY,
+                        noColor: invocation.noColor,
+                        width: invocation.stdout.columns,
+                    }));
+                return 0;
+        }
+    }),
+});
+const acceptCommand = Object.freeze({
+    name: "accept",
+    summary: "accept exact historical Attempt locators",
+    options: exports.ACCEPT_CLI_OPTIONS,
+    run: (argv) => effect_1.Effect.gen(function* () {
+        const input = yield* parsed(argv, exports.ACCEPT_CLI_OPTIONS);
+        if (input.values.help === true)
+            return yield* write("stdout", ACCEPT_HELP).pipe(effect_1.Effect.as(0));
+        if (input.positionals.length === 0)
+            return yield* write("stderr", "usage: niceeval accept @<locator>...\n").pipe(effect_1.Effect.as(1));
+        const { invocation, config } = yield* factsAndConfig();
+        const result = yield* index_ts_3.experimentHost.accept({ cwd: invocation.cwd, config, locators: Object.freeze(input.positionals), ...(typeof input.values.record === "string" ? { recordRoot: input.values.record } : {}) }).pipe(effect_1.Effect.mapError((cause) => failure("accept", cause, 1, (0, index_ts_2.t)("cli.accept.failed", {
+            error: cause.message,
+        }))));
+        yield* write("stdout", acceptText(result));
+        return 0;
+    }),
+});
+const sessionCommand = Object.freeze({
+    name: "session",
+    summary: "inspect project-local ephemeral Invocation status",
+    options: exports.SESSION_CLI_OPTIONS,
+    run: (argv) => effect_1.Effect.gen(function* () {
+        const input = yield* parsed(argv, exports.SESSION_CLI_OPTIONS);
+        if (input.values.help === true)
+            return yield* write("stdout", SESSION_HELP).pipe(effect_1.Effect.as(0));
+        const [verb = "list", value] = input.positionals;
+        const facts = yield* application_ts_1.CliInvocationFacts;
+        const invocation = yield* facts.facts.pipe(effect_1.Effect.mapError((cause) => failure("read invocation facts", cause)));
+        if (verb === "list") {
+            const result = yield* index_ts_3.experimentHost.invocationStatus.list({ cwd: invocation.cwd, ...(input.values.all === true ? { all: true } : {}), ...(value === undefined ? {} : { experimentSelector: value }) }).pipe(effect_1.Effect.mapError((cause) => failure("list invocation status", cause)));
+            yield* write("stdout", input.values.json === true ? jsonDocument(result) : (0, session_ts_1.renderSessionListText)(result, Date.now(), input.values.all === true));
+            return 0;
+        }
+        if (verb === "show" && value !== undefined && input.positionals.length === 2) {
+            const result = yield* index_ts_3.experimentHost.invocationStatus.show({ cwd: invocation.cwd, invocationSelector: value }).pipe(effect_1.Effect.mapError((cause) => failure("show invocation status", cause)));
+            yield* write("stdout", input.values.json === true ? jsonDocument(result) : (0, session_ts_1.renderSessionShowText)(result));
+            return 0;
+        }
+        return yield* write("stderr", "usage: niceeval session [list [<experiment-prefix>] | show <invocation-id>]\n").pipe(effect_1.Effect.as(1));
+    }),
+});
+/** The composition root receives frozen feature values; it never registers services. */
+exports.experimentCliContributions = Object.freeze([
+    checkCommand,
+    expCommand,
+    debugCommand,
+    acceptCommand,
+    sessionCommand,
+]);
+//# sourceMappingURL=contribution.cjs.map