engineering-behavior-observatory 0.2.1

package/dist/src/cli.js

@@ -0,0 +1,957 @@
+#!/usr/bin/env node
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, mkdtempSync, realpathSync, renameSync, rmSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+import { assertNoDuplicateJsonKeys, canonicalizeMetadata, digestMetadata, validateArtifact, validateExportManifest, validateRunManifestEvidence, writeMetadataAtomically } from "./artifacts.js";
+import { aggregateEvaluation } from "./aggregation.js";
+import { serveAtlas, writeAtlas } from "./atlas.js";
+import { buildCorpusIndex, packPortableExport, queryCorpusIndex, readCorpusIndex, unpackPortableExport, validateCorpusIndex, writeCorpusIndex, } from "./corpus.js";
+import { runAgentSdkQueueEntry } from "./agent-sdk-runner.js";
+import { validateRetainedBehaviorAssertion } from "./behavior-assertions.js";
+import { runCodexQueueEntry } from "./codex-run.js";
+import { runCursorSdkQueueEntry } from "./cursor-sdk-runner.js";
+import { runPiQueueEntry } from "./pi.js";
+import { createPortableRunBundleExport } from "./exports.js";
+import { assertCalibrationDestination, importReviewDecision, selectReviewSample, summarizeCalibration, revalidateReviewSample, validateReviewHistory, writeReviewPacket, } from "./human-calibration.js";
+import { assessComparisonEligibility, assessLegacyComparisonEligibility } from "./normalization-integrity.js";
+import { runAgentSdkSemanticJudge, } from "./semantic-judge.js";
+import { createRetainedStructuralObservationSet } from "./structural-observations.js";
+import { admitTaskPacket, formatErrors, freezeTaskPacket, inspectTaskPacket, statusTaskPacket, } from "./task-packets.js";
+import { compileRunQueue, inspectRunQueue, readBoundedFile, readRunQueue, validateRunQueue, writeRunQueue, } from "./scheduler.js";
+const usage = `Usage: ebo [--help] | validate <artifact.json>... | task-packet <command> ...
+       ebo matrix compile <experiment.json> <bundle-root> <queue.json> [--freeze-locator <task-id>=<path>]
+       ebo queue inspect <queue.json>
+       ebo queue validate <queue.json> [experiment.json] [--bundle-root <bundle-root>]
+       ebo agent-sdk run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]
+       ebo codex run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]
+       ebo cursor run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]
+       ebo pi run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]
+       ebo export create <run-bundle-root> <policy.json> <export-root>
+       ebo corpus build <corpus-root> <index.jsonl>
+       ebo corpus query <index.jsonl> [--kind|--run|--attempt|--task|--model|--harness|--assessment-mode|--terminal|--failure-class|--verifier-status|--capture|--export-status|--sharing-class <value>]
+       ebo corpus validate <corpus-root> <index.jsonl>
+       ebo corpus pack <export-root> <policy.json> <archive.tar.gz>
+       ebo corpus unpack <archive.tar.gz> <destination-root>
+       ebo comparison check <request.json>
+       ebo aggregate build <request.json> <output.json>
+       ebo atlas build <request.json> <output-root> [--share] [--filter <name=value>]
+       ebo atlas serve <request.json> [--port <port>]
+       ebo observations create <run-bundle-root> <output.json>
+       ebo observations corpus <corpus-root> <index.jsonl> <output-root> [corpus query flags]
+       ebo assertions validate <run-bundle-root> <assertion.json> [review.json]
+       ebo judge run <run-bundle-root> <observations.json> <request.json> <output-root>
+       ebo calibration sample <sources.json> <criteria.json> <selection.json>
+       ebo calibration packet <selection.json> <output-root>
+       ebo calibration inspect <packet.json> <assertion-id> [event-id]
+       ebo calibration binding <selection.json> <assertion-id> [history.json]
+       ebo calibration <import|adjudicate> <selection.json> <history.json> <decision.json>
+       ebo calibration summarize <selection.json> <history.json> <summary.json>
+
+Engineering Behavior Observatory
+`;
+const taskPacketUsage = `Usage: ebo task-packet <validate|admit|freeze|status> <bundle-root> <packet.json> [freeze-record.json]
+`;
+export function main(args = process.argv.slice(2), write = (message) => {
+    process.stdout.write(message);
+}, dependencies = {}) {
+    if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+        write(usage);
+        return 0;
+    }
+    if (args[0] === "task-packet") {
+        return runTaskPacketCommand(args.slice(1), write);
+    }
+    if ((args[0] === "matrix" && args[1] === "compile") || args[0] === "compile") {
+        return compileQueue(args[0] === "matrix" ? args.slice(2) : args.slice(1), write);
+    }
+    if (args[0] === "queue" && args[1] === "inspect") {
+        if (args[2] === undefined) {
+            write("Usage: ebo queue inspect <queue.json>\n");
+            return 1;
+        }
+        try {
+            const inspection = inspectRunQueue(readRunQueue(args[2]));
+            write(`Run queue ${args[2]}: ${inspection.entryCount} entr${inspection.entryCount === 1 ? "y" : "ies"}; seed=${inspection.seed}; strategy=${inspection.strategy}.\n`);
+            return 0;
+        }
+        catch (error) {
+            write(`${errorMessage(error)}\n`);
+            return 1;
+        }
+    }
+    if (args[0] === "queue" && args[1] === "validate") {
+        return validateQueue(args.slice(2), write);
+    }
+    if (args[0] === "agent-sdk" && args[1] === "run") {
+        return runAgentSdkCommand(args.slice(2), write);
+    }
+    if (args[0] === "codex" && args[1] === "run") {
+        return runCodexCommand(args.slice(2), write);
+    }
+    if (args[0] === "cursor" && args[1] === "run") {
+        return runCursorSdkCommand(args.slice(2), write);
+    }
+    if (args[0] === "pi" && args[1] === "run") {
+        return runPiCommand(args.slice(2), write);
+    }
+    if (args[0] === "export" && args[1] === "create") {
+        return createExportCommand(args.slice(2), write);
+    }
+    if (args[0] === "corpus") {
+        return runCorpusCommand(args.slice(1), write);
+    }
+    if (args[0] === "comparison" && args[1] === "check") {
+        if (args[2] === undefined || args.length !== 3) {
+            write("Usage: ebo comparison check <request.json>\n");
+            return 1;
+        }
+        try {
+            const request = readJson(args[2]);
+            const report = request.schemaVersion === "ebo.comparison-request/v1"
+                ? assessLegacyComparisonEligibility(request)
+                : assessComparisonEligibility(request);
+            write(`${canonicalizeMetadata(report)}\n`);
+            return report.status === "unsupported" ? 1 : 0;
+        }
+        catch (error) {
+            write(`${errorMessage(error)}\n`);
+            return 1;
+        }
+    }
+    if (args[0] === "aggregate" && args[1] === "build") {
+        return runAggregationCommand(args.slice(2), write);
+    }
+    if (args[0] === "atlas") {
+        return (async () => {
+            try {
+                if (args[1] === "serve" && args[2] && (args.length === 3 || (args.length === 5 && args[3] === "--port"))) {
+                    const server = await serveAtlas(args[2], args[4] === undefined ? 13011 : Number(args[4]));
+                    const address = server.address();
+                    write(`Atlas listening at http://127.0.0.1:${typeof address === "object" && address ? address.port : 13011}\n`);
+                    return 0;
+                }
+                if (args[1] !== "build" || !args[2] || !args[3])
+                    throw new Error("Usage: ebo atlas build <request.json> <output-root> [--share] [--filter <name=value>] | atlas serve <request.json> [--port <port>]");
+                const filters = {};
+                let share = false;
+                for (let i = 4; i < args.length; i++) {
+                    if (args[i] === "--share") {
+                        share = true;
+                        continue;
+                    }
+                    if (args[i] !== "--filter" || !args[i + 1]?.includes("="))
+                        throw new Error("Unknown Atlas argument.");
+                    const pair = args[++i];
+                    const offset = pair.indexOf("=");
+                    filters[pair.slice(0, offset)] = pair.slice(offset + 1);
+                }
+                const view = await writeAtlas(args[2], args[3], filters, share);
+                write(`Built Atlas: ${view.report.sourcePopulation.selectedAttempts} selected attempts; ${view.mode}; ${view.cohortDigest}\n`);
+                return 0;
+            }
+            catch (error) {
+                write(`${errorMessage(error)}\n`);
+                return 1;
+            }
+        })();
+    }
+    if (args[0] === "observations") {
+        return runObservationsCommand(args.slice(1), write);
+    }
+    if (args[0] === "assertions" && args[1] === "validate") {
+        const bundleRoot = args[2];
+        const assertionPath = args[3];
+        const reviewPath = args[4];
+        if (bundleRoot === undefined || assertionPath === undefined || args.length > 5) {
+            write("Usage: ebo assertions validate <run-bundle-root> <assertion.json> [review.json]\n");
+            return 1;
+        }
+        try {
+            const assertion = readJson(assertionPath);
+            const review = reviewPath === undefined ? undefined : readJson(reviewPath);
+            return validateRetainedBehaviorAssertion(bundleRoot, assertion, review).then((citations) => {
+                write(`Validated behavior assertion "${assertion.id}" (${citations.length} citation(s); review=${review?.state ?? "unreviewed"}).\n`);
+                return 0;
+            }, (error) => {
+                write(`${errorMessage(error)}\n`);
+                return 1;
+            });
+        }
+        catch (error) {
+            write(`${errorMessage(error)}\n`);
+            return 1;
+        }
+    }
+    if (args[0] === "judge" && args[1] === "run") {
+        const bundleRoot = args[2];
+        const observationsPath = args[3];
+        const requestPath = args[4];
+        const outputRoot = args[5];
+        if (bundleRoot === undefined || observationsPath === undefined || requestPath === undefined
+            || outputRoot === undefined || args.length !== 6) {
+            write("Usage: ebo judge run <run-bundle-root> <observations.json> <request.json> <output-root>\n");
+            return 1;
+        }
+        const controller = new AbortController();
+        const abort = () => controller.abort();
+        const cleanup = () => {
+            process.off("SIGINT", abort);
+            process.off("SIGTERM", abort);
+        };
+        process.on("SIGINT", abort);
+        process.on("SIGTERM", abort);
+        try {
+            return runAgentSdkSemanticJudge({
+                bundleRoot,
+                observations: readJson(observationsPath),
+                request: readJson(requestPath),
+                outputRoot,
+                signal: controller.signal,
+                ...(dependencies.semanticJudgeBackend === undefined ? {} : { backend: dependencies.semanticJudgeBackend }),
+            }).then((record) => {
+                write(`${canonicalizeMetadata(record)}\n`);
+                return record.status === "proposed" ? 0 : 1;
+            }, (error) => {
+                write(`${errorMessage(error)}\n`);
+                return 1;
+            }).finally(cleanup);
+        }
+        catch (error) {
+            cleanup();
+            write(`${errorMessage(error)}\n`);
+            return 1;
+        }
+    }
+    if (args[0] === "calibration") {
+        return runCalibrationCommand(args.slice(1), write);
+    }
+    if (args[0] === "validate") {
+        if (args.length === 1) {
+            write("Usage: ebo validate <artifact.json>...\n");
+            return 1;
+        }
+        const artifacts = args.slice(1).map((artifact) => {
+            try {
+                return { artifact, document: readJson(artifact) };
+            }
+            catch (error) {
+                return {
+                    artifact,
+                    error: { artifact, schemaVersion: "unknown", field: "/", message: error instanceof Error ? error.message : "Unable to read artifact." },
+                };
+            }
+        });
+        const errors = artifacts.flatMap(({ artifact, document, error }) => {
+            if (error !== undefined)
+                return [error];
+            if (document !== undefined && typeof document === "object" && document !== null
+                && document.schemaVersion === "ebo.run-queue/v1") {
+                return validateRunQueue(document, undefined, artifact);
+            }
+            const validation = validateArtifact(artifact, document);
+            return document !== undefined && typeof document === "object" && document !== null
+                && document.schemaVersion === "run-manifest/v1"
+                ? [...validation, ...validateRunManifestEvidence(artifact, document, dirname(artifact))]
+                : validation;
+        });
+        for (const { artifact, document } of artifacts) {
+            if (document === undefined || typeof document !== "object" || document === null
+                || document.schemaVersion !== "export-manifest/v1")
+                continue;
+            const bundleId = document.bundleId;
+            const containingEntry = artifacts.find(({ document: candidate }) => candidate !== undefined && typeof candidate === "object" && candidate !== null
+                && candidate.schemaVersion === "run-manifest/v1"
+                && candidate.bundleId === bundleId);
+            errors.push(...validateExportManifest(artifact, document, containingEntry?.document, containingEntry === undefined ? undefined : dirname(containingEntry.artifact)));
+        }
+        if (errors.length === 0) {
+            write(`Validated ${args.length - 1} artifact(s).\n`);
+            return 0;
+        }
+        for (const error of errors) {
+            write(`${error.artifact} [${error.schemaVersion}] ${error.field}: ${error.message}\n`);
+        }
+        return 1;
+    }
+    process.stderr.write(`Unknown argument: ${args[0]}\n`);
+    return 1;
+}
+async function runAggregationCommand(args, write) {
+    const [requestPath, outputPath] = args;
+    if (requestPath === undefined || outputPath === undefined || args.length !== 2) {
+        write("Usage: ebo aggregate build <request.json> <output.json>\n");
+        return 1;
+    }
+    try {
+        const request = readJson(requestPath);
+        const errors = validateArtifact(requestPath, request);
+        if (errors.length > 0)
+            throw new Error(errors.map(({ field, message }) => `${field}: ${message}`).join("\n"));
+        const base = dirname(resolve(requestPath));
+        const source = request.sources;
+        const corpusRoot = resolve(base, source.corpusRoot);
+        const corpusIndexPath = resolve(base, source.corpusIndex);
+        const corpusEntries = readCorpusIndex(corpusIndexPath);
+        const corpusIssues = validateCorpusIndex(corpusRoot, corpusEntries);
+        if (corpusIssues.length > 0)
+            throw new Error(`Corpus index is not current: ${corpusIssues[0].manifestPath} ${corpusIssues[0].message}`);
+        const resolveJson = (path, label) => {
+            const resolved = resolve(base, path);
+            const value = readJson(resolved);
+            const validation = validateArtifact(resolved, value);
+            if (validation.length > 0)
+                throw new Error(`${label} ${validation[0].field}: ${validation[0].message}`);
+            return value;
+        };
+        const destination = resolve(outputPath);
+        prepareDerivedParent(corpusRoot, destination);
+        const report = await aggregateEvaluation({
+            lineage: {
+                requestDigest: `sha256:${digestMetadata(request).value}`,
+                corpusIndexDigest: `sha256:${digestMetadata(corpusEntries).value}`,
+            },
+            corpusEntries,
+            observationSets: source.observationSets.map(({ bundleRoot, path }) => ({
+                bundleRoot: resolve(base, bundleRoot),
+                document: resolveJson(path, "Structural observation set"),
+            })),
+            assertions: source.assertions.map(({ bundleRoot, path }) => ({
+                bundleRoot: resolve(base, bundleRoot),
+                document: resolveJson(path, "Behavior assertion"),
+            })),
+            calibrations: source.calibrations.map(({ selection, history }) => ({
+                selection: resolveJson(selection, "Review sample"),
+                history: resolveJson(history, "Review history"),
+            })),
+            comparisons: request.comparisons.map(({ eligibilityGates, ...comparison }) => ({
+                ...comparison,
+                eligibility: eligibilityGates.map(({ request: comparisonRequest, report }) => ({
+                    request: resolveJson(comparisonRequest, "Comparison request"),
+                    report: resolveJson(report, "Comparison report"),
+                })),
+            })),
+        }, request);
+        await writeMetadataAtomically(dirname(destination), basename(destination), report, undefined, { overwrite: false });
+        write(`Built ${report.groups.length} aggregate group(s) and ${report.comparisons.length} matched comparison(s).\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+async function runCalibrationCommand(args, write) {
+    const [command, first, second, third] = args;
+    try {
+        if (command === "sample" && first !== undefined && second !== undefined && third !== undefined && args.length === 4) {
+            const sources = readJson(first);
+            assertCalibrationDestination(sources.sources.map(({ bundleRoot }) => bundleRoot), third);
+            const sample = await selectReviewSample(sources, readJson(second));
+            await writeMetadataAtomically(dirname(resolve(third)), basename(third), sample, undefined, { overwrite: false });
+            write(`Selected ${sample.candidates.length} of ${sample.population.eligibleAssertionIds.length} eligible behavior assertions.\n`);
+            return 0;
+        }
+        if (command === "packet" && first !== undefined && second !== undefined && args.length === 3) {
+            const sample = readJson(first);
+            await writeReviewPacket(sample, second);
+            write(`Created local review packet for ${sample.candidates.length} assertion(s).\n`);
+            return 0;
+        }
+        if (command === "inspect" && first !== undefined && second !== undefined && args.length >= 3 && args.length <= 4) {
+            const packet = readJson(first);
+            const errors = validateArtifact(first, packet);
+            if (errors.length > 0)
+                throw new Error(errors.map(({ field, message }) => `${field}: ${message}`).join("\n"));
+            const items = packet.items ?? [];
+            const matching = items.filter(({ assertionBinding }) => matchesAssertionSelector(assertionBinding, second));
+            if (matching.length !== 1)
+                throw new Error(matching.length === 0
+                    ? `Review packet has no assertion "${second}".` : `Review packet assertion "${second}" is ambiguous; append @<digest>.`);
+            const item = matching[0];
+            const value = third === undefined ? item : item.citations?.find(({ eventId }) => eventId === third);
+            if (value === undefined)
+                throw new Error(`Review assertion "${second}" has no citation "${third}".`);
+            write(`${canonicalizeMetadata(value)}\n`);
+            return 0;
+        }
+        if (command === "binding" && first !== undefined && second !== undefined && args.length >= 3 && args.length <= 4) {
+            const selection = readJson(first);
+            await revalidateReviewSample(selection);
+            const matching = selection.candidates.filter(({ assertion }) => matchesAssertionSelector(assertion, second));
+            if (matching.length !== 1)
+                throw new Error(matching.length === 0
+                    ? `Review sample has no assertion "${second}".` : `Review sample assertion "${second}" is ambiguous; append @<digest>.`);
+            const candidate = matching[0];
+            const history = third === undefined ? undefined : readJson(third);
+            if (history !== undefined)
+                validateReviewHistory(selection, history);
+            write(`${canonicalizeMetadata({
+                assertion: candidate.assertion,
+                previousHistory: history === undefined || history.decisions.length === 0 ? null : {
+                    schemaVersion: history.schemaVersion,
+                    digest: `sha256:${digestMetadata(history).value}`,
+                },
+            })}\n`);
+            return 0;
+        }
+        if ((command === "import" || command === "adjudicate") && first !== undefined && second !== undefined && third !== undefined && args.length === 4) {
+            const decision = readJson(third);
+            const expectedKind = command === "adjudicate" ? "adjudication" : "review";
+            if (decision.kind !== expectedKind)
+                throw new Error(`The calibration ${command} command requires a ${expectedKind} decision.`);
+            const result = await importReviewDecision(readJson(first), second, decision);
+            write(`${result.appended ? "Appended" : "Already imported"} human ${command === "adjudicate" ? "adjudication" : "review"} decision.\n`);
+            return 0;
+        }
+        if (command === "summarize" && first !== undefined && second !== undefined && third !== undefined && args.length === 4) {
+            const selection = readJson(first);
+            assertCalibrationDestination(selection.sources.sources.map(({ bundleRoot }) => bundleRoot), third);
+            const summary = await summarizeCalibration(selection, readJson(second));
+            await writeMetadataAtomically(dirname(resolve(third)), basename(third), summary, undefined, { overwrite: false });
+            write(`Summarized ${summary.totals.selectedAssertions} selected assertion(s); confirmed=${summary.totals.confirmedEligibleAssertions}, unresolved=${summary.totals.unresolvedAssertions}.\n`);
+            return 0;
+        }
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    write("Usage: ebo calibration <sample|packet|inspect|binding|import|adjudicate|summarize> ...\n");
+    return 1;
+}
+function matchesAssertionSelector(assertion, selector) {
+    if (assertion === undefined)
+        return false;
+    const separator = selector.lastIndexOf("@sha256:");
+    return separator < 0 ? assertion.id === selector
+        : assertion.id === selector.slice(0, separator) && assertion.digest === selector.slice(separator + 1);
+}
+function runCorpusCommand(args, write) {
+    const [command, first, second, third] = args;
+    try {
+        if (command === "build" && first !== undefined && second !== undefined && args.length === 3) {
+            const entries = buildCorpusIndex(first);
+            writeCorpusIndex(second, entries);
+            write(`Built ${entries.length} corpus index entr${entries.length === 1 ? "y" : "ies"}.\n`);
+            return 0;
+        }
+        if (command === "query" && first !== undefined) {
+            const query = parseCorpusQuery(args.slice(2));
+            for (const entry of queryCorpusIndex(readCorpusIndex(first), query))
+                write(`${canonicalizeMetadata(entry)}\n`);
+            return 0;
+        }
+        if (command === "validate" && first !== undefined && second !== undefined && args.length === 3) {
+            const issues = validateCorpusIndex(first, readCorpusIndex(second));
+            for (const issue of issues)
+                write(`${issue.manifestPath} [${issue.kind}]: ${issue.message}\n`);
+            if (issues.length > 0)
+                return 1;
+            write("Corpus index is current and all indexed evidence is reachable.\n");
+            return 0;
+        }
+        if (command === "pack" && first !== undefined && second !== undefined && third !== undefined && args.length === 4) {
+            return packPortableExport(first, third, readJson(second)).then((digest) => {
+                write(`Packed portable export (${digest}).\n`);
+                return 0;
+            }, (error) => {
+                write(`${errorMessage(error)}\n`);
+                return 1;
+            });
+        }
+        if (command === "unpack" && first !== undefined && second !== undefined && args.length === 3) {
+            const manifest = unpackPortableExport(first, second);
+            write(`Unpacked portable export ${manifest.bundleId} (${manifest.artifacts.length} artifacts).\n`);
+            return 0;
+        }
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    write("Usage: ebo corpus <build|query|validate|pack|unpack> ...\n");
+    return 1;
+}
+function parseCorpusQuery(args) {
+    const fields = {
+        "--kind": "manifestKind",
+        "--run": "runId",
+        "--trial": "runId",
+        "--attempt": "attemptId",
+        "--task": "taskId",
+        "--model": "modelId",
+        "--harness": "harnessId",
+        "--assessment-mode": "assessmentMode",
+        "--terminal": "terminalState",
+        "--failure-class": "failureClass",
+        "--verifier-status": "verifierStatus",
+        "--capture": "captureQualification",
+        "--export-status": "exportStatus",
+        "--sharing-class": "sharingClass",
+    };
+    const query = {};
+    for (let index = 0; index < args.length; index += 2) {
+        const field = fields[args[index]];
+        const value = args[index + 1];
+        if (field === undefined || value === undefined)
+            throw new Error("Corpus query filters require a supported flag and value.");
+        query[field] = value;
+    }
+    return query;
+}
+async function runObservationsCommand(args, write) {
+    const [command, first, second, third] = args;
+    try {
+        if (command === "create" && first !== undefined && second !== undefined && args.length === 3) {
+            assertDerivedDestination(first, second);
+            const report = await createRetainedStructuralObservationSet(first);
+            await writeObservationReport(second, report, first);
+            write(`Created ${report.observations.length} structural observations for attempt ${report.attemptId}.\n`);
+            return 0;
+        }
+        if (command === "corpus" && first !== undefined && second !== undefined && third !== undefined) {
+            assertDerivedDestination(first, third);
+            const index = readCorpusIndex(second);
+            const issues = validateCorpusIndex(first, index);
+            if (issues.length > 0)
+                throw new Error(`Corpus index is not current: ${issues[0].manifestPath} ${issues[0].message}`);
+            const selected = queryCorpusIndex(index, { ...parseCorpusQuery(args.slice(4)), manifestKind: "run" });
+            if (selected.length === 0)
+                throw new Error("Corpus selection matched no retained run bundles.");
+            const outputRoot = resolve(third);
+            const outputParent = prepareDerivedParent(first, outputRoot);
+            if (existsSync(outputRoot))
+                throw new Error("Structural observation corpus destination already exists.");
+            const stagingRoot = mkdtempSync(join(outputParent, ".ebo-observations-"));
+            let published = false;
+            try {
+                for (const entry of selected) {
+                    if (entry.runId === undefined || entry.attemptId === undefined || entry.issues.length > 0)
+                        throw new Error(`Corpus entry ${entry.manifestPath} is not observation-ready.`);
+                    const bundleRoot = dirname(join(resolve(first), ...entry.manifestPath.split("/")));
+                    const report = await createRetainedStructuralObservationSet(bundleRoot);
+                    await writeObservationReport(join(stagingRoot, observationFileName(entry.runId, entry.attemptId)), report, first);
+                }
+                renameSync(stagingRoot, outputRoot);
+                published = true;
+            }
+            finally {
+                if (!published)
+                    rmSync(stagingRoot, { recursive: true, force: true });
+            }
+            write(`Created structural observations for ${selected.length} corpus run bundle(s).\n`);
+            return 0;
+        }
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    write("Usage: ebo observations <create|corpus> ...\n");
+    return 1;
+}
+async function writeObservationReport(path, report, sourceRoot) {
+    const destination = resolve(path);
+    prepareDerivedParent(sourceRoot, destination);
+    await writeMetadataAtomically(dirname(destination), basename(destination), report, undefined, { overwrite: false });
+}
+function prepareDerivedParent(sourceRoot, destination) {
+    const source = realpathSync(sourceRoot);
+    const parent = dirname(resolve(destination));
+    let existing = parent;
+    while (!existsSync(existing)) {
+        const next = dirname(existing);
+        if (next === existing)
+            break;
+        existing = next;
+    }
+    assertOutside(source, realpathSync(existing));
+    mkdirSync(parent, { recursive: true, mode: 0o700 });
+    const resolved = realpathSync(parent);
+    assertOutside(source, resolved);
+    return resolved;
+}
+function assertDerivedDestination(sourceRoot, destination) {
+    const source = resolve(sourceRoot);
+    const output = resolve(destination);
+    assertOutside(source, output);
+}
+function assertOutside(source, output) {
+    const locator = relative(source, output);
+    if (locator === "" || locator !== ".." && !locator.startsWith(`..${sep}`)) {
+        throw new Error("Structural observations must be written outside immutable source evidence.");
+    }
+}
+function observationFileName(runId, attemptId) {
+    return `sha256-${createHash("sha256").update(JSON.stringify([runId, attemptId])).digest("hex")}.json`;
+}
+async function runAgentSdkCommand(args, write) {
+    const agentSdkRunUsage = "Usage: ebo agent-sdk run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]\n";
+    const positional = [];
+    let workspaceRoot;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--workspace-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write(agentSdkRunUsage);
+                return 1;
+            }
+            workspaceRoot = value;
+        }
+        else
+            positional.push(args[index]);
+    }
+    const [bundleRoot, queuePath, runId, outputRoot] = positional;
+    if (bundleRoot === undefined || queuePath === undefined || runId === undefined
+        || outputRoot === undefined || positional.length !== 4) {
+        write(agentSdkRunUsage);
+        return 1;
+    }
+    try {
+        const summary = await runAgentSdkQueueEntry({
+            bundleRoot,
+            queuePath,
+            runId,
+            outputRoot,
+            ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+        });
+        write(`${canonicalizeMetadata(summary)}\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+async function runCodexCommand(args, write) {
+    const commandUsage = "Usage: ebo codex run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]\n";
+    const positional = [];
+    let workspaceRoot;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--workspace-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write(commandUsage);
+                return 1;
+            }
+            workspaceRoot = value;
+        }
+        else
+            positional.push(args[index]);
+    }
+    const [bundleRoot, queuePath, runId, outputRoot] = positional;
+    if (bundleRoot === undefined || queuePath === undefined || runId === undefined
+        || outputRoot === undefined || positional.length !== 4) {
+        write(commandUsage);
+        return 1;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.on("SIGINT", abort);
+    process.on("SIGTERM", abort);
+    try {
+        const summary = await runCodexQueueEntry({
+            bundleRoot,
+            queuePath,
+            runId,
+            outputRoot,
+            signal: controller.signal,
+            ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+        });
+        write(`${canonicalizeMetadata(summary)}\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", abort);
+        process.off("SIGTERM", abort);
+    }
+}
+async function runCursorSdkCommand(args, write) {
+    const commandUsage = "Usage: ebo cursor run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]\n";
+    const positional = [];
+    let workspaceRoot;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--workspace-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write(commandUsage);
+                return 1;
+            }
+            workspaceRoot = value;
+        }
+        else
+            positional.push(args[index]);
+    }
+    const [bundleRoot, queuePath, runId, outputRoot] = positional;
+    if (bundleRoot === undefined || queuePath === undefined || runId === undefined
+        || outputRoot === undefined || positional.length !== 4) {
+        write(commandUsage);
+        return 1;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.on("SIGINT", abort);
+    process.on("SIGTERM", abort);
+    try {
+        const summary = await runCursorSdkQueueEntry({
+            bundleRoot,
+            queuePath,
+            runId,
+            outputRoot,
+            signal: controller.signal,
+            ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+        });
+        write(`${canonicalizeMetadata(summary)}\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", abort);
+        process.off("SIGTERM", abort);
+    }
+}
+async function runPiCommand(args, write) {
+    const commandUsage = "Usage: ebo pi run <bundle-root> <queue.json> <run-id> <output-root> [--workspace-root <path>]\n";
+    const positional = [];
+    let workspaceRoot;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--workspace-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write(commandUsage);
+                return 1;
+            }
+            workspaceRoot = value;
+        }
+        else
+            positional.push(args[index]);
+    }
+    const [bundleRoot, queuePath, runId, outputRoot] = positional;
+    if (bundleRoot === undefined || queuePath === undefined || runId === undefined
+        || outputRoot === undefined || positional.length !== 4) {
+        write(commandUsage);
+        return 1;
+    }
+    const controller = new AbortController();
+    const abort = () => controller.abort();
+    process.on("SIGINT", abort);
+    process.on("SIGTERM", abort);
+    try {
+        const summary = await runPiQueueEntry({
+            bundleRoot,
+            queuePath,
+            runId,
+            outputRoot,
+            signal: controller.signal,
+            ...(workspaceRoot === undefined ? {} : { workspaceRoot }),
+        });
+        write(`${canonicalizeMetadata(summary)}\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+    finally {
+        process.off("SIGINT", abort);
+        process.off("SIGTERM", abort);
+    }
+}
+async function createExportCommand(args, write) {
+    const [sourceRoot, policyPath, exportRoot] = args;
+    if (sourceRoot === undefined || policyPath === undefined || exportRoot === undefined || args.length !== 3) {
+        write("Usage: ebo export create <run-bundle-root> <policy.json> <export-root>\n");
+        return 1;
+    }
+    try {
+        const manifest = await createPortableRunBundleExport({
+            sourceRoot,
+            destinationRoot: exportRoot,
+            policy: readJson(policyPath),
+        });
+        write(`Created ${manifest.sharingClass} portable export (${manifest.status}) for bundle ${manifest.bundleId} at ${exportRoot}.\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function compileQueue(args, write) {
+    const positional = [];
+    let bundleRoot;
+    let outputPath;
+    const freezeLocators = {};
+    for (let index = 0; index < args.length; index += 1) {
+        const argument = args[index];
+        if (argument === "--bundle-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write("Usage: ebo matrix compile <experiment.json> <bundle-root> <queue.json> [--freeze-locator <task-id>=<path>]\n");
+                return 1;
+            }
+            bundleRoot = value;
+        }
+        else if (argument === "--output") {
+            outputPath = args[++index];
+        }
+        else if (argument === "--freeze-locator") {
+            const value = args[++index];
+            const separator = value?.indexOf("=") ?? -1;
+            if (separator <= 0 || separator === value.length - 1) {
+                write("Usage: ebo matrix compile <experiment.json> <bundle-root> <queue.json> [--freeze-locator <task-id>=<path>]\n");
+                return 1;
+            }
+            freezeLocators[value.slice(0, separator)] = value.slice(separator + 1);
+        }
+        else {
+            positional.push(argument);
+        }
+    }
+    const experimentPath = positional.shift();
+    if (experimentPath === undefined) {
+        write("Usage: ebo matrix compile <experiment.json> <bundle-root> <queue.json> [--freeze-locator <task-id>=<path>]\n");
+        return 1;
+    }
+    if (bundleRoot === undefined && positional.length === 2)
+        bundleRoot = positional.shift();
+    if (outputPath === undefined && positional.length === 1)
+        outputPath = positional.shift();
+    if (bundleRoot === undefined)
+        bundleRoot = dirname(experimentPath);
+    if (outputPath === undefined) {
+        write("Usage: ebo matrix compile <experiment.json> <bundle-root> <queue.json> [--freeze-locator <task-id>=<path>]\n");
+        return 1;
+    }
+    try {
+        const experiment = readJson(experimentPath);
+        const queue = compileRunQueue(experiment, {
+            bundleRoot,
+            ...(Object.keys(freezeLocators).length === 0 ? {} : { freezeLocators }),
+        });
+        writeRunQueue(outputPath, queue);
+        write(`Compiled ${queue.entries.length} run entr${queue.entries.length === 1 ? "y" : "ies"} into ${outputPath}. Seed: ${queue.seed}.\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function validateQueue(args, write) {
+    const positional = [];
+    let bundleRoot;
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === "--bundle-root") {
+            const value = args[++index];
+            if (value === undefined || value.startsWith("--")) {
+                write("Usage: ebo queue validate <queue.json> [experiment.json] [--bundle-root <bundle-root>]\n");
+                return 1;
+            }
+            bundleRoot = value;
+        }
+        else
+            positional.push(args[index]);
+    }
+    const queuePath = positional[0];
+    if (queuePath === undefined || positional.length > 2) {
+        write("Usage: ebo queue validate <queue.json> [experiment.json] [--bundle-root <bundle-root>]\n");
+        return 1;
+    }
+    try {
+        const experiment = positional[1] === undefined ? undefined : readJson(positional[1]);
+        const queue = readRunQueue(queuePath, experiment, bundleRoot === undefined ? {} : { bundleRoot });
+        const entryCount = queue.entries.length;
+        write(`Validated run queue ${queuePath} (${entryCount} entr${entryCount === 1 ? "y" : "ies"}).\n`);
+        return 0;
+    }
+    catch (error) {
+        write(`${errorMessage(error)}\n`);
+        return 1;
+    }
+}
+function readJson(path) {
+    const text = new TextDecoder("utf-8", { fatal: true }).decode(readBoundedFile(path));
+    assertNoDuplicateJsonKeys(text);
+    return JSON.parse(text);
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : "Unable to process run queue.";
+}
+function runTaskPacketCommand(args, write) {
+    const [command, bundleRoot, packetLocator, freezeLocator] = args;
+    if (command === undefined || bundleRoot === undefined || packetLocator === undefined
+        || !["validate", "admit", "freeze", "status"].includes(command)) {
+        write(taskPacketUsage);
+        return 1;
+    }
+    try {
+        if (command === "validate") {
+            const inspection = inspectTaskPacket(bundleRoot, packetLocator);
+            if (inspection.errors.length > 0) {
+                write(`${formatErrors(inspection.errors)}\n`);
+                return 1;
+            }
+            write(`Validated task packet "${inspection.packet.id}".\n`);
+            return 0;
+        }
+        if (command === "admit") {
+            const inspection = admitTaskPacket(bundleRoot, packetLocator);
+            if (inspection.errors.length > 0) {
+                write(`${formatErrors(inspection.errors)}\n`);
+                return 1;
+            }
+            write(`Admitted task packet "${inspection.packet.id}".\n`);
+            return 0;
+        }
+        if (command === "freeze") {
+            const record = freezeTaskPacket(bundleRoot, packetLocator, freezeLocator);
+            write(`Frozen task packet "${record.packetId}" (aggregate ${record.aggregateDigest.algorithm}:${record.aggregateDigest.value}).\n`);
+            return 0;
+        }
+        const status = statusTaskPacket(bundleRoot, packetLocator, freezeLocator);
+        write(`Task packet status: ${status.status}\n`);
+        if (status.packetId !== null)
+            write(`Packet: ${status.packetId}\n`);
+        if (status.packetDigest !== null)
+            write(`Packet digest: ${status.packetDigest.algorithm}:${status.packetDigest.value}\n`);
+        if (status.aggregateDigest !== null)
+            write(`Aggregate digest: ${status.aggregateDigest.algorithm}:${status.aggregateDigest.value}\n`);
+        for (const mismatch of status.mismatches)
+            write(`Mismatch: ${mismatch}\n`);
+        if (status.errors.length > 0)
+            write(`${formatErrors(status.errors)}\n`);
+        return status.status === "frozen" ? 0 : 1;
+    }
+    catch (error) {
+        write(`${error instanceof Error ? error.message : "Task packet command failed."}\n`);
+        return 1;
+    }
+}
+function isDirectExecution(entryPath = process.argv[1]) {
+    if (entryPath === undefined) {
+        return false;
+    }
+    try {
+        return import.meta.url === pathToFileURL(realpathSync(entryPath)).href;
+    }
+    catch {
+        return false;
+    }
+}
+if (isDirectExecution()) {
+    Promise.resolve(main()).then((exitCode) => {
+        process.exitCode = exitCode;
+    }, (error) => {
+        process.stderr.write(`${errorMessage(error)}\n`);
+        process.exitCode = 1;
+    });
+}