@kestrel-agents/ruhroh 0.5.0-beta.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kestrel-agents
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,114 @@
+<p align="center">
+  <img src="assets/ruhroh-logo.png" alt="Ruhroh logo" width="220">
+</p>
+
+# <img src="assets/ruhroh-badge.png" alt="" width="28" align="absmiddle"> Ruhroh
+
+Ruhroh is the **Real-User Harness for Repair-Oriented Harbor**.
+
+Ruhroh runs real-user task scenarios against coding agents through adapters,
+preserves the full implementation journey, and runs a terminal evaluator over
+the final delivered workspace.
+
+Ruhroh is agent-agnostic. Kestrel is one reference run-agent adapter, not the
+benchmark itself. Harbor is the execution substrate.
+
+## Install
+
+```bash
+pnpm add -D @kestrel-agents/ruhroh
+```
+
+## Quickstart
+
+Create scenarios under `ruhroh/scenarios/<id>/`, or use the bundled scenarios
+under `node_modules/@kestrel-agents/ruhroh/scenarios`, then run:
+
+```bash
+pnpm ruhroh --list
+pnpm ruhroh --scenario simple-newsletter --generate-only
+pnpm ruhroh --scenario simple-newsletter --adapter ./path/to/agent-adapter --dry-run
+```
+
+In this repo, the same package CLI is available with:
+
+```bash
+pnpm ruhroh --scenario-dir examples/scenarios --list
+pnpm ruhroh --scenario-dir examples/scenarios --scenario simple-newsletter --generate-only
+```
+
+This package currently contains the portable TypeScript surfaces:
+
+- scenario schema and validation;
+- run-agent adapter interfaces and capability compatibility helpers;
+- eval and final result types;
+- verdict mapping helpers;
+- env forwarding and redaction helpers;
+- Harbor command construction helpers;
+- JSON scenario discovery and Harbor task generation helpers.
+
+## Scenario Generation
+
+Ruhroh can load JSON scenarios from:
+
+```text
+ruhroh/scenarios/<id>/
+  scenario.json
+  instruction.md
+  assets/
+```
+
+and generate local Harbor task directories under:
+
+```text
+.generated/ruhroh/harbor/tasks/<scenario-id>/
+```
+
+The generated Harbor verifier is app-agnostic. It only validates that the
+structured Ruhroh result exists and maps to a passing score/reward; it does not
+perform required-file, route, command, or source-text checks.
+
+The public API exports:
+
+- `discoverRuhrohScenarios()`
+- `loadRuhrohScenario()`
+- `generateHarborTask()`
+- `generateHarborDataset()`
+
+The package CLI exposes this through:
+
+```bash
+pnpm ruhroh --scenario-dir ruhroh/scenarios --generate-only
+pnpm ruhroh --scenario-dir ruhroh/scenarios --dry-run
+```
+
+This package ships the reusable scenario source under `scenarios/` and the
+package-owned Python Harbor runtime under `python/ruhroh`. Run-agents are wired
+into this runtime as command adapters through
+`RUHROH_RUN_AGENT_COMMAND`; terminal evaluation can be supplied through
+`RUHROH_EVAL_COMMAND` or fixture eval variables.
+
+Kestrel is a consumer adapter, not a Ruhroh package dependency. The Harbor
+harness is package-owned for generated Ruhroh tasks.
+
+## Docs
+
+- Architecture: `docs/architecture.md`
+- Scenario format: `docs/scenario-format.md`
+- Adapter protocol: `docs/adapter-protocol.md`
+- Custom-shell adapter: `docs/custom-shell.md`
+- Harbor: `docs/harbor.md`
+- Eval-agent: `docs/eval-agent.md`
+- Artifacts: `docs/artifacts.md`
+- CI: `docs/ci.md`
+- Security: `docs/security.md`
+- Limitations: `docs/limitations.md`
+- Public repo layout: `docs/public-repo-layout.md`
+
+## Security
+
+Scenario prompts and assets are untrusted input. Run-agents should mutate only
+benchmark workspaces. Eval-agent inspection should happen against a copied
+workspace. Secrets must pass through allowlisted environment variables, and
+dry-run output must never print secret values. Generated Harbor verifiers do
+not perform app-goal checks.

package/dist/adapters.d.ts

@@ -0,0 +1,97 @@
+export type RuhrohContinuityLevel = "native_session" | "workspace_plus_transcript" | "workspace_only";
+export type RuhrohCompletionConfidence = "explicit" | "adapter_inferred";
+export type RuhrohCompletionDoneReason = "goal_satisfied";
+export type RuhrohCompletionNotDoneReason = "agent_requested_continue" | "missing_completion_signal" | "context_checkpoint" | "partial_progress";
+export type RuhrohCompletionTerminalFailureReason = "cannot_satisfy" | "policy_blocked" | "out_of_scope" | "runtime_failure" | "infra_failure";
+export interface RuhrohEvidenceRef {
+    kind: string;
+    ref: string;
+    summary: string;
+}
+export type RuhrohCompletionStatus = {
+    state: "done";
+    reason: RuhrohCompletionDoneReason;
+    confidence: RuhrohCompletionConfidence;
+    evidenceRefs: RuhrohEvidenceRef[];
+} | {
+    state: "not_done";
+    reason: RuhrohCompletionNotDoneReason;
+    evidenceRefs: RuhrohEvidenceRef[];
+} | {
+    state: "terminal_failure";
+    reason: RuhrohCompletionTerminalFailureReason;
+    evidenceRefs: RuhrohEvidenceRef[];
+};
+export interface PrepareRunAgentInput {
+    scenarioId: string;
+    workspacePath: string;
+    runRootPath: string;
+}
+export interface PrepareRunAgentResult {
+    artifactPaths: Record<string, string>;
+}
+export interface StartSessionInput {
+    scenarioId: string;
+    workspacePath: string;
+}
+export interface StartSessionResult {
+    sessionHandle: string;
+    artifactPaths: Record<string, string>;
+}
+export interface RunTurnInput {
+    iteration: number;
+    message: string;
+    workspacePath: string;
+}
+export interface RunTurnResult {
+    iteration: number;
+    status: "completed" | "failed" | "timeout";
+    failureKind?: string | undefined;
+    runId?: string | undefined;
+    threadId?: string | undefined;
+    sessionHandle: string;
+    transcriptPath?: string | undefined;
+    eventLogPath?: string | undefined;
+    artifactPaths: Record<string, string>;
+    raw: unknown;
+}
+export interface DetectCompletionInput {
+    turn: RunTurnResult;
+}
+export interface CollectArtifactsInput {
+    sessionHandle: string;
+}
+export interface RunAgentArtifactManifest {
+    adapterId: string;
+    continuityLevel: RuhrohContinuityLevel;
+    sessionHandle: string;
+    runIds: string[];
+    transcriptPaths: string[];
+    eventLogPaths: string[];
+    artifactPaths: Record<string, string>;
+}
+export interface CleanupInput {
+    sessionHandle: string;
+}
+export interface RuhrohRunAgentAdapter {
+    readonly id: string;
+    readonly continuityLevel: RuhrohContinuityLevel;
+    prepare(input: PrepareRunAgentInput): Promise<PrepareRunAgentResult>;
+    startSession(input: StartSessionInput): Promise<StartSessionResult>;
+    runTurn(input: RunTurnInput): Promise<RunTurnResult>;
+    detectCompletion(input: DetectCompletionInput): Promise<RuhrohCompletionStatus>;
+    collectArtifacts(input: CollectArtifactsInput): Promise<RunAgentArtifactManifest>;
+    cleanup?(input: CleanupInput): Promise<void>;
+}
+export interface RuhrohRunAgentAdapterCapabilities {
+    adapter: string;
+    continuity: RuhrohContinuityLevel;
+    tools: string[];
+    network: boolean;
+}
+export declare function adapterSatisfiesRequirements(adapter: RuhrohRunAgentAdapterCapabilities, requirements: {
+    continuity: RuhrohContinuityLevel;
+    tools: string[];
+    network: boolean;
+}): string[];
+//# sourceMappingURL=adapters.d.ts.map

package/dist/adapters.d.ts.map

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

package/dist/adapters.js

@@ -0,0 +1,21 @@
+const CONTINUITY_RANK = {
+    workspace_only: 1,
+    workspace_plus_transcript: 2,
+    native_session: 3,
+};
+export function adapterSatisfiesRequirements(adapter, requirements) {
+    const errors = [];
+    if (CONTINUITY_RANK[adapter.continuity] < CONTINUITY_RANK[requirements.continuity]) {
+        errors.push(`adapter ${adapter.adapter} does not satisfy required continuity ${requirements.continuity}`);
+    }
+    for (const tool of requirements.tools) {
+        if (!adapter.tools.includes(tool)) {
+            errors.push(`adapter ${adapter.adapter} does not provide required tool ${tool}`);
+        }
+    }
+    if (requirements.network && !adapter.network) {
+        errors.push(`adapter ${adapter.adapter} does not provide required network access`);
+    }
+    return errors;
+}
+//# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapters.js","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAuHA,MAAM,eAAe,GAA0C;IAC7D,cAAc,EAAE,CAAC;IACjB,yBAAyB,EAAE,CAAC;IAC5B,cAAc,EAAE,CAAC;CAClB,CAAC;AAEF,MAAM,UAAU,4BAA4B,CAC1C,OAA0C,EAC1C,YAIC;IAED,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,eAAe,CAAC,OAAO,CAAC,UAAU,CAAC,GAAG,eAAe,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE,CAAC;QACnF,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,OAAO,yCAAyC,YAAY,CAAC,UAAU,EAAE,CAAC,CAAC;IAC5G,CAAC;IACD,KAAK,MAAM,IAAI,IAAI,YAAY,CAAC,KAAK,EAAE,CAAC;QACtC,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;YAClC,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,OAAO,mCAAmC,IAAI,EAAE,CAAC,CAAC;QACnF,CAAC;IACH,CAAC;IACD,IAAI,YAAY,CAAC,OAAO,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;QAC7C,MAAM,CAAC,IAAI,CAAC,WAAW,OAAO,CAAC,OAAO,2CAA2C,CAAC,CAAC;IACrF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/builtin-scenarios.d.ts

@@ -0,0 +1,8 @@
+import { type LoadedRuhrohScenario } from "./generate.js";
+import { type RuhrohScenario, type RuhrohScenarioTier } from "./scenarios.js";
+export declare function resolveRuhrohPackageRootFromModule(importMetaUrl?: string): string;
+export declare function resolveRuhrohBuiltinScenarioDir(packageRoot?: string): string;
+export declare function loadBuiltinRuhrohScenarios(scenarioDir?: string): LoadedRuhrohScenario[];
+export declare function getBuiltinRuhrohScenarioById(id: string, scenarioDir?: string): RuhrohScenario | undefined;
+export declare function getBuiltinRuhrohScenariosByTier(tier: RuhrohScenarioTier, scenarioDir?: string): RuhrohScenario[];
+//# sourceMappingURL=builtin-scenarios.d.ts.map

package/dist/builtin-scenarios.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-scenarios.d.ts","sourceRoot":"","sources":["../src/builtin-scenarios.ts"],"names":[],"mappings":"AAGA,OAAO,EAA+C,KAAK,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACvG,OAAO,EAGL,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACxB,MAAM,gBAAgB,CAAC;AAExB,wBAAgB,kCAAkC,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,CAIlG;AAED,wBAAgB,+BAA+B,CAAC,WAAW,GAAE,MAA6C,GAAG,MAAM,CAElH;AAED,wBAAgB,0BAA0B,CACxC,WAAW,GAAE,MAA0C,GACtD,oBAAoB,EAAE,CAExB;AAED,wBAAgB,4BAA4B,CAC1C,EAAE,EAAE,MAAM,EACV,WAAW,GAAE,MAA0C,GACtD,cAAc,GAAG,SAAS,CAE5B;AAED,wBAAgB,+BAA+B,CAC7C,IAAI,EAAE,kBAAkB,EACxB,WAAW,GAAE,MAA0C,GACtD,cAAc,EAAE,CAElB"}

package/dist/builtin-scenarios.js

@@ -0,0 +1,22 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { discoverRuhrohScenarios, loadRuhrohScenario } from "./generate.js";
+import { getRuhrohScenarioById, getRuhrohScenariosByTier, } from "./scenarios.js";
+export function resolveRuhrohPackageRootFromModule(importMetaUrl = import.meta.url) {
+    const moduleDir = path.dirname(fileURLToPath(importMetaUrl));
+    const basename = path.basename(moduleDir);
+    return basename === "dist" || basename === "src" ? path.dirname(moduleDir) : moduleDir;
+}
+export function resolveRuhrohBuiltinScenarioDir(packageRoot = resolveRuhrohPackageRootFromModule()) {
+    return path.join(packageRoot, "scenarios");
+}
+export function loadBuiltinRuhrohScenarios(scenarioDir = resolveRuhrohBuiltinScenarioDir()) {
+    return discoverRuhrohScenarios(scenarioDir).map((source) => loadRuhrohScenario(source));
+}
+export function getBuiltinRuhrohScenarioById(id, scenarioDir = resolveRuhrohBuiltinScenarioDir()) {
+    return getRuhrohScenarioById(loadBuiltinRuhrohScenarios(scenarioDir).map((loaded) => loaded.scenario), id);
+}
+export function getBuiltinRuhrohScenariosByTier(tier, scenarioDir = resolveRuhrohBuiltinScenarioDir()) {
+    return getRuhrohScenariosByTier(loadBuiltinRuhrohScenarios(scenarioDir).map((loaded) => loaded.scenario), tier);
+}
+//# sourceMappingURL=builtin-scenarios.js.map

package/dist/builtin-scenarios.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builtin-scenarios.js","sourceRoot":"","sources":["../src/builtin-scenarios.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAA6B,MAAM,eAAe,CAAC;AACvG,OAAO,EACL,qBAAqB,EACrB,wBAAwB,GAGzB,MAAM,gBAAgB,CAAC;AAExB,MAAM,UAAU,kCAAkC,CAAC,gBAAwB,MAAM,CAAC,IAAI,CAAC,GAAG;IACxF,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CAAC;IAC7D,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;IAC1C,OAAO,QAAQ,KAAK,MAAM,IAAI,QAAQ,KAAK,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;AACzF,CAAC;AAED,MAAM,UAAU,+BAA+B,CAAC,cAAsB,kCAAkC,EAAE;IACxG,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,0BAA0B,CACxC,cAAsB,+BAA+B,EAAE;IAEvD,OAAO,uBAAuB,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,4BAA4B,CAC1C,EAAU,EACV,cAAsB,+BAA+B,EAAE;IAEvD,OAAO,qBAAqB,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,EAAE,CAAC,CAAC;AAC7G,CAAC;AAED,MAAM,UAAU,+BAA+B,CAC7C,IAAwB,EACxB,cAAsB,+BAA+B,EAAE;IAEvD,OAAO,wBAAwB,CAAC,0BAA0B,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,CAAC;AAClH,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import type { RuhrohScenarioTier } from "./scenarios.js";
+interface RuntimeDeps {
+    spawn: typeof spawnSync;
+    env: NodeJS.ProcessEnv;
+    cwd: string;
+    stdout: Pick<NodeJS.WriteStream, "write">;
+    stderr: Pick<NodeJS.WriteStream, "write">;
+}
+export interface RuhrohCliOptions {
+    command: "run" | "generate";
+    list: boolean;
+    dryRun: boolean;
+    generateOnly: boolean;
+    harborBin: string;
+    scenarioDir: string;
+    generatedDir: string;
+    scenarioId?: string | undefined;
+    tier?: RuhrohScenarioTier | undefined;
+    iterations?: number | undefined;
+    adapter?: string | undefined;
+}
+export declare function parseRuhrohCliArgs(argv: string[], cwd?: string): RuhrohCliOptions;
+export declare function runRuhrohCli(argv: string[], deps: RuntimeDeps): Promise<number>;
+export declare function resolveRuhrohPackageRoot(): string;
+export declare function resolveRuhrohPythonPath(): string;
+export declare function buildHarborSpawnEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAyB,MAAM,oBAAoB,CAAC;AAOtE,OAAO,KAAK,EAAkB,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,UAAU,WAAW;IACnB,KAAK,EAAE,OAAO,SAAS,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;IAC1C,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,WAAW,EAAE,OAAO,CAAC,CAAC;CAC3C;AAED,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,KAAK,GAAG,UAAU,CAAC;IAC5B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,OAAO,CAAC;IAChB,YAAY,EAAE,OAAO,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,IAAI,CAAC,EAAE,kBAAkB,GAAG,SAAS,CAAC;IACtC,UAAU,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CAC9B;AAcD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,GAAE,MAAsB,GAAG,gBAAgB,CAgFhG;AAED,wBAAsB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAyFrF;AAgED,wBAAgB,wBAAwB,IAAI,MAAM,CAIjD;AAED,wBAAgB,uBAAuB,IAAI,MAAM,CAEhD;AAED,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAAC,UAAU,CAQ7E"}

package/dist/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { RUHROH_ARTIFACTS, RUHROH_HARBOR_AGENT_IMPORT_PATH, buildRuhrohHarborCommands } from "./harbor.js";
+import { discoverRuhrohScenarios, generateHarborDataset, loadRuhrohScenario } from "./generate.js";
+class HelpRequested extends Error {
+}
+export function parseRuhrohCliArgs(argv, cwd = process.cwd()) {
+    const options = {
+        command: "run",
+        list: false,
+        dryRun: false,
+        generateOnly: false,
+        harborBin: "harbor",
+        scenarioDir: path.join(resolveRuhrohPackageRoot(), "scenarios"),
+        generatedDir: path.resolve(cwd, ".generated", "ruhroh"),
+        tier: "smoke",
+    };
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === undefined || arg === "--") {
+            continue;
+        }
+        if (index === 0 && (arg === "run" || arg === "generate")) {
+            options.command = arg;
+            if (arg === "generate") {
+                options.generateOnly = true;
+            }
+            continue;
+        }
+        if (arg === "--help" || arg === "-h") {
+            throw new HelpRequested();
+        }
+        if (arg === "--list") {
+            options.list = true;
+            continue;
+        }
+        if (arg === "--dry-run") {
+            options.dryRun = true;
+            continue;
+        }
+        if (arg === "--generate-only") {
+            options.generateOnly = true;
+            continue;
+        }
+        if (arg === "--scenario") {
+            options.scenarioId = assertSafeScenarioId(readValue(argv, index, arg));
+            options.tier = undefined;
+            index += 1;
+            continue;
+        }
+        if (arg === "--tier") {
+            options.tier = parseTier(readValue(argv, index, arg));
+            options.scenarioId = undefined;
+            index += 1;
+            continue;
+        }
+        if (arg === "--scenario-dir") {
+            options.scenarioDir = path.resolve(cwd, readValue(argv, index, arg));
+            index += 1;
+            continue;
+        }
+        if (arg === "--generated-dir") {
+            options.generatedDir = path.resolve(cwd, readValue(argv, index, arg));
+            index += 1;
+            continue;
+        }
+        if (arg === "--iterations") {
+            options.iterations = parsePositiveInteger(readValue(argv, index, arg), arg);
+            index += 1;
+            continue;
+        }
+        if (arg === "--adapter") {
+            options.adapter = readValue(argv, index, arg);
+            index += 1;
+            continue;
+        }
+        if (arg === "--harbor-bin") {
+            options.harborBin = readValue(argv, index, arg);
+            index += 1;
+            continue;
+        }
+        throw new Error(`Unknown argument: ${arg}`);
+    }
+    return options;
+}
+export async function runRuhrohCli(argv, deps) {
+    let options;
+    try {
+        options = parseRuhrohCliArgs(argv, deps.cwd);
+    }
+    catch (error) {
+        if (error instanceof HelpRequested) {
+            deps.stdout.write(helpText());
+            return 0;
+        }
+        deps.stderr.write(`ruhroh failed: ${error instanceof Error ? error.message : String(error)}\n\n`);
+        deps.stderr.write(helpText());
+        return 1;
+    }
+    let loaded;
+    try {
+        loaded = discoverRuhrohScenarios(options.scenarioDir).map((source) => loadRuhrohScenario(source));
+        if (loaded.length === 0) {
+            throw new Error(`No Ruhroh scenarios found in ${options.scenarioDir}`);
+        }
+    }
+    catch (error) {
+        deps.stderr.write(`ruhroh failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    if (options.list) {
+        for (const { scenario } of loaded) {
+            deps.stdout.write(`${scenario.id}\t${scenario.tier}\t${scenario.title}\n`);
+        }
+        return 0;
+    }
+    let selected;
+    try {
+        selected = selectScenarios(loaded, options);
+    }
+    catch (error) {
+        deps.stderr.write(`ruhroh failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    let datasetPath = path.join(options.generatedDir, "harbor");
+    if (!options.dryRun || options.generateOnly) {
+        const generated = generateHarborDataset({
+            scenarios: selected,
+            outputRoot: options.generatedDir,
+            agentImportPath: RUHROH_HARBOR_AGENT_IMPORT_PATH,
+            artifacts: RUHROH_ARTIFACTS,
+        });
+        datasetPath = generated.datasetPath;
+        for (const task of generated.tasks) {
+            deps.stdout.write(`[ruhroh] generated ${task.scenarioId}: ${path.relative(deps.cwd, task.taskDir)}\n`);
+        }
+    }
+    if (options.generateOnly) {
+        deps.stdout.write("[ruhroh] generate-only complete. No Harbor tasks were started.\n");
+        return 0;
+    }
+    let adapter;
+    try {
+        adapter = resolveAdapterSelection(options, deps.cwd, deps.env);
+    }
+    catch (error) {
+        deps.stderr.write(`ruhroh failed: ${error instanceof Error ? error.message : String(error)}\n`);
+        return 1;
+    }
+    const commands = buildCommands(selected.map((item) => item.scenario), options, datasetPath, adapter);
+    deps.stdout.write(`[ruhroh] selected=${commands.map((command) => command.scenarioId).join(",")}\n`);
+    for (const command of commands) {
+        deps.stdout.write(`[ruhroh] harbor: ${formatCommand(options.harborBin, command.args)}\n`);
+    }
+    if (options.dryRun) {
+        deps.stdout.write("[ruhroh] dry run complete. No Harbor tasks were started.\n");
+        return 0;
+    }
+    let failed = false;
+    const harborEnv = buildHarborSpawnEnv(adapter.env);
+    for (const command of commands) {
+        const result = deps.spawn(options.harborBin, command.args, {
+            cwd: deps.cwd,
+            env: harborEnv,
+            stdio: "inherit",
+        });
+        if (result.status !== 0 || result.error !== undefined) {
+            deps.stderr.write(`[ruhroh] Harbor command failed for ${command.scenarioId}.\n${formatSpawnFailure(result)}`);
+            failed = true;
+        }
+    }
+    return failed ? 1 : 0;
+}
+function selectScenarios(loaded, options) {
+    if (options.scenarioId !== undefined) {
+        const scenario = loaded.find((item) => item.scenario.id === options.scenarioId);
+        if (scenario === undefined) {
+            throw new Error(`Unknown Ruhroh scenario: ${options.scenarioId}`);
+        }
+        return [scenario];
+    }
+    return loaded.filter((item) => item.scenario.tier === (options.tier ?? "smoke"));
+}
+function buildCommands(scenarios, options, datasetPath, adapter) {
+    return buildRuhrohHarborCommands({
+        scenarios,
+        adapter: adapter.adapterId,
+        datasetPath,
+        iterations: options.iterations,
+        env: adapter.env,
+        agentImportPath: RUHROH_HARBOR_AGENT_IMPORT_PATH,
+        artifacts: RUHROH_ARTIFACTS,
+    });
+}
+function resolveAdapterSelection(options, cwd, env) {
+    const adapter = options.adapter?.trim();
+    if (adapter === undefined || adapter.length === 0) {
+        throw new Error("--adapter is required for ruhroh run and dry-run commands");
+    }
+    if (looksLikeAdapterCommand(adapter)) {
+        const command = adapter.includes(" ")
+            ? adapter
+            : path.resolve(cwd, adapter);
+        const adapterId = adapterIdFromCommand(command);
+        return {
+            adapterId,
+            env: {
+                ...env,
+                RUHROH_RUN_AGENT_COMMAND: command,
+            },
+        };
+    }
+    return { adapterId: adapter, env };
+}
+function looksLikeAdapterCommand(adapter) {
+    return /\s/u.test(adapter) || adapter.startsWith(".") || adapter.startsWith("/") || adapter.includes(path.sep);
+}
+function adapterIdFromCommand(command) {
+    const firstPathLikePart = command.split(/\s+/u).find((part) => part.includes(path.sep)) ?? command;
+    return path.basename(firstPathLikePart).replace(/\.[cm]?[jt]sx?$/u, "") || "command";
+}
+export function resolveRuhrohPackageRoot() {
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    const basename = path.basename(moduleDir);
+    return basename === "dist" || basename === "src" ? path.dirname(moduleDir) : moduleDir;
+}
+export function resolveRuhrohPythonPath() {
+    return path.join(resolveRuhrohPackageRoot(), "python");
+}
+export function buildHarborSpawnEnv(env) {
+    const pythonPath = resolveRuhrohPythonPath();
+    return {
+        ...env,
+        PYTHONPATH: env.PYTHONPATH === undefined || env.PYTHONPATH.trim().length === 0
+            ? pythonPath
+            : `${pythonPath}${path.delimiter}${env.PYTHONPATH}`,
+    };
+}
+function parseTier(value) {
+    if (value === "smoke" || value === "nightly" || value === "release") {
+        return value;
+    }
+    throw new Error(`Unknown Ruhroh tier: ${value}`);
+}
+function parsePositiveInteger(value, arg) {
+    const parsed = Number.parseInt(value, 10);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error(`${arg} must be a positive integer`);
+    }
+    return parsed;
+}
+function assertSafeScenarioId(value) {
+    if (!/^[a-zA-Z0-9._-]+$/u.test(value) || value === "." || value === "..") {
+        throw new Error(`Unsafe Ruhroh scenario id: ${value}`);
+    }
+    return value;
+}
+function readValue(argv, index, arg) {
+    const value = argv[index + 1];
+    if (value === undefined || value.length === 0) {
+        throw new Error(`${arg} requires a value`);
+    }
+    return value;
+}
+function formatCommand(command, args) {
+    return [command, ...args].map((part) => (/^[a-zA-Z0-9_./:=@-]+$/u.test(part) ? part : JSON.stringify(part))).join(" ");
+}
+function formatSpawnFailure(result) {
+    const stdout = result.stdout ?? Buffer.alloc(0);
+    const stderr = result.stderr ?? Buffer.alloc(0);
+    const parts = [
+        `status=${String(result.status)}`,
+        result.error === undefined ? "" : `error=${result.error.message}`,
+        stdout.length > 0 ? `stdout:\n${stdout.toString("utf8")}` : "",
+        stderr.length > 0 ? `stderr:\n${stderr.toString("utf8")}` : "",
+    ].filter(Boolean);
+    return `${parts.join("\n")}\n`;
+}
+function helpText() {
+    return `Usage: ruhroh [run|generate] [options]\n\nCommon commands:\n  ruhroh --list\n  ruhroh --scenario simple-newsletter --generate-only\n  ruhroh --scenario simple-newsletter --dry-run\n  ruhroh generate --tier smoke\n\nOptions:\n  --list                    List JSON scenarios.\n  --scenario <id>           Select one scenario.\n  --tier <tier>             Select scenarios in tier: smoke, nightly, release. Default: smoke.\n  --scenario-dir <path>     Scenario root. Default: bundled package scenarios.\n  --generated-dir <path>    Generated output root. Default: .generated/ruhroh.\n  --iterations <n>          Override implementation iterations.\n  --adapter <id-or-command> Select run-agent adapter by id or command path. Required for run/dry-run.\n  --generate-only           Generate Harbor task directories without running Harbor.\n  --harbor-bin <path>       Harbor binary. Default: harbor.\n  --dry-run                 Print Harbor commands without writing tasks or running Harbor.\n`;
+}
+async function main() {
+    const code = await runRuhrohCli(process.argv.slice(2), {
+        spawn: spawnSync,
+        env: process.env,
+        cwd: process.cwd(),
+        stdout: process.stdout,
+        stderr: process.stderr,
+    });
+    process.exitCode = code;
+}
+if (isDirectCliInvocation()) {
+    main().catch((error) => {
+        process.stderr.write(`ruhroh failed: ${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    });
+}
+function isDirectCliInvocation() {
+    if (process.argv[1] === undefined) {
+        return false;
+    }
+    const modulePath = fileURLToPath(import.meta.url);
+    try {
+        return realpathSync(process.argv[1]) === realpathSync(modulePath);
+    }
+    catch {
+        return path.resolve(process.argv[1]) === modulePath;
+    }
+}
+//# sourceMappingURL=cli.js.map