@unimatrix27/ralph-harness 1.0.0

package/dist/lib/credential-syncer.d.ts

@@ -0,0 +1,27 @@
+import { type AwsClients } from "./aws-clients.js";
+export declare const MODULE_PREFIX = "credential-syncer";
+export declare const DEFAULTS: {
+    readonly ssmKey: "/ralph/claude-oauth-credential";
+    readonly kmsAlias: "alias/ralph";
+    readonly keychainService: "Claude Code-credentials";
+};
+export type CredentialSyncerExitCode = 1 | 3 | 4;
+export declare class CredentialSyncerError extends Error {
+    readonly code: CredentialSyncerExitCode;
+    constructor(code: CredentialSyncerExitCode, message: string);
+}
+export declare function moduleErr(message: string): string;
+export declare function moduleInfo(message: string): string;
+export type Logger = (line: string) => void;
+export type SecurityReader = (service: string) => string;
+export interface SyncCredentialOptions {
+    clients: AwsClients;
+    ssmKey?: string;
+    kmsAlias?: string;
+    keychainService?: string;
+    region?: string;
+    info?: Logger;
+    readKeychain?: SecurityReader;
+}
+export declare function syncCredential(opts: SyncCredentialOptions): Promise<void>;
+//# sourceMappingURL=credential-syncer.d.ts.map

package/dist/lib/credential-syncer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credential-syncer.d.ts","sourceRoot":"","sources":["../../src/lib/credential-syncer.ts"],"names":[],"mappings":"AAgCA,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAM/D,eAAO,MAAM,aAAa,sBAAsB,CAAC;AAEjD,eAAO,MAAM,QAAQ;;;;CAIX,CAAC;AAEX,MAAM,MAAM,wBAAwB,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;AAEjD,qBAAa,qBAAsB,SAAQ,KAAK;aAE5B,IAAI,EAAE,wBAAwB;gBAA9B,IAAI,EAAE,wBAAwB,EAC9C,OAAO,EAAE,MAAM;CAKlB;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAElD;AAED,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAM5C,MAAM,MAAM,cAAc,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;AAEzD,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,UAAU,CAAC;IACpB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,cAAc,CAAC;CAC/B;AAMD,wBAAsB,cAAc,CAClC,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,IAAI,CAAC,CA6Ff"}

package/dist/lib/credential-syncer.js

@@ -0,0 +1,116 @@
+// credential-syncer — extract the macOS Keychain `Claude Code-credentials`
+// entry and write it into the SSM SecureString that the EC2 worker reads at
+// launch. Re-run after every desktop `claude /login`.
+//
+// Public surface:
+//   syncCredential(opts)
+//
+// Errors throw CredentialSyncerError with a code field that the CLI maps to
+// its exit code.
+//
+// Exit codes (must match the bash port at lib/credential-syncer.sh —
+// preserved across the port so existing operator runbooks/automation read
+// the same numbers):
+//   0   success (no error thrown)
+//   2   usage error                                         (CLI only)
+//   3   Keychain entry missing, empty, or not JSON
+//   4   AWS credentials not configured
+//   1   any other propagated failure
+//
+// Security:
+//   - The credential is read into a single string variable, then passed to
+//     the SSM SDK as the request body of PutParameter. It never appears on
+//     argv (the SDK marshals it as JSON inside the HTTPS request).
+//   - We never log, echo, or include the credential value in any error
+//     message. The "not valid JSON" error message also omits the bytes (so
+//     a malformed credential doesn't leak via stderr).
+//   - The Keychain read goes through src/lib/security-runner — that wrapper
+//     is the single point that touches the credential bytes via subprocess.
+import { PutParameterCommand } from "@aws-sdk/client-ssm";
+import { GetCallerIdentityCommand } from "@aws-sdk/client-sts";
+import { AWS_REGION } from "./aws-clients.js";
+import { SecurityRunnerError, readGenericPassword, } from "./security-runner.js";
+export const MODULE_PREFIX = "credential-syncer";
+export const DEFAULTS = {
+    ssmKey: "/ralph/claude-oauth-credential",
+    kmsAlias: "alias/ralph",
+    keychainService: "Claude Code-credentials",
+};
+export class CredentialSyncerError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "CredentialSyncerError";
+    }
+}
+export function moduleErr(message) {
+    return `${MODULE_PREFIX}: error: ${message}`;
+}
+export function moduleInfo(message) {
+    return `${MODULE_PREFIX}: ${message}`;
+}
+const defaultInfo = (line) => process.stdout.write(`${line}\n`);
+// syncCredential — read the Keychain entry, validate it parses as JSON, and
+// upload it to the SSM SecureString at <ssmKey>. Always overwrites because
+// the parameter is created with a placeholder by aws-bootstrap and must be
+// updated in place.
+export async function syncCredential(opts) {
+    const { clients, ssmKey = DEFAULTS.ssmKey, kmsAlias = DEFAULTS.kmsAlias, keychainService = DEFAULTS.keychainService, region = AWS_REGION, info = defaultInfo, readKeychain = readGenericPassword, } = opts;
+    // 1. AWS auth precheck — exits 4 with a useful message if the operator
+    //    forgot to authenticate. Cheaper to fail here than after the Keychain
+    //    read because the Keychain read can pop a UI prompt on macOS.
+    try {
+        await clients.sts.send(new GetCallerIdentityCommand({}));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CredentialSyncerError(4, moduleErr(`AWS credentials not configured. Run 'aws configure' or set AWS_PROFILE. (${detail})`));
+    }
+    // 2. Read the Keychain entry. Fail with code 3 on missing/empty/non-JSON.
+    let cred;
+    try {
+        cred = readKeychain(keychainService);
+    }
+    catch (err) {
+        if (err instanceof SecurityRunnerError) {
+            throw new CredentialSyncerError(3, moduleErr(`Keychain entry '${keychainService}' not found. Log into the Claude desktop app first (claude /login).`));
+        }
+        throw err;
+    }
+    if (cred.length === 0) {
+        throw new CredentialSyncerError(3, moduleErr(`Keychain entry '${keychainService}' is empty.`));
+    }
+    try {
+        JSON.parse(cred);
+    }
+    catch {
+        // Do NOT include the credential bytes in the error message — the bash
+        // port is explicit about this and the bats test asserts non-leakage of
+        // even a malformed value.
+        throw new CredentialSyncerError(3, moduleErr(`Keychain entry '${keychainService}' is not valid JSON. Re-login via the Claude desktop app and retry.`));
+    }
+    // 3. Upload via SSM PutParameter. The SDK serializes the value into the
+    //    request body — never argv. The Overwrite flag matches the bash port:
+    //    aws-bootstrap creates the parameter with a placeholder, we overwrite
+    //    it on every run. Type+KeyId need not be repeated when overwriting,
+    //    but we set them so a fresh sync against a non-bootstrapped account
+    //    still works (defensive — usually the operator runs bootstrap-aws
+    //    first).
+    info(moduleInfo(`uploading credential to ${ssmKey} (region=${region}, kms=${kmsAlias})`));
+    try {
+        await clients.ssm.send(new PutParameterCommand({
+            Name: ssmKey,
+            Type: "SecureString",
+            KeyId: kmsAlias,
+            Value: cred,
+            Overwrite: true,
+        }));
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        throw new CredentialSyncerError(1, moduleErr(`ssm put-parameter failed for ${ssmKey}: ${detail}`));
+    }
+    info(moduleInfo(`uploaded credential to ${ssmKey}`));
+}
+//# sourceMappingURL=credential-syncer.js.map

package/dist/lib/credential-syncer.js.map

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

package/dist/lib/ec2-orchestrator.d.ts

@@ -0,0 +1,38 @@
+import { type RunClaudeOptions } from "./claude-runner.js";
+import { type Phase, type Sink } from "./structured-log-emitter.js";
+export declare const MODULE_PREFIX = "ec2-orchestrator";
+export declare class OrchestratorError extends Error {
+    readonly exitCode: number;
+    constructor(exitCode: number, message: string);
+}
+export interface OrchestratorConfig {
+    targetRepo: string;
+    awsRegion: string;
+    workDir: string;
+    defaultBranch: string;
+    configPath: string;
+    launchTag: string;
+    outDir: string;
+    discoveryPromptPath: string;
+    implementationPromptPath: string;
+    reviewPromptPath: string;
+    reviewWaitSec: number;
+}
+export declare function resolveOrchestratorConfig(env: NodeJS.ProcessEnv, packageRoot: string): OrchestratorConfig;
+type ClaudeRunner = (prompt: string, opts?: RunClaudeOptions) => Promise<{
+    exitCode: number;
+}>;
+type Sleep = (ms: number) => Promise<void>;
+export interface RunOptions {
+    env?: NodeJS.ProcessEnv;
+    packageRoot?: string;
+    claude?: ClaudeRunner;
+    sleep?: Sleep;
+    sink?: Sink;
+    clock?: () => Date;
+    runSystemSetup?: (workDir: string) => Promise<void>;
+}
+export declare function mergeSetupEnvFile(path: string, env: NodeJS.ProcessEnv): number;
+export declare function run(opts?: RunOptions): Promise<number>;
+export type { Phase };
+//# sourceMappingURL=ec2-orchestrator.d.ts.map

package/dist/lib/ec2-orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ec2-orchestrator.d.ts","sourceRoot":"","sources":["../../src/lib/ec2-orchestrator.ts"],"names":[],"mappings":"AAsCA,OAAO,EAAa,KAAK,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAUtE,OAAO,EAML,KAAK,KAAK,EACV,KAAK,IAAI,EACV,MAAM,6BAA6B,CAAC;AAMrC,eAAO,MAAM,aAAa,qBAAqB,CAAC;AAEhD,qBAAa,iBAAkB,SAAQ,KAAK;aACd,QAAQ,EAAE,MAAM;gBAAhB,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAI9D;AAKD,MAAM,WAAW,kBAAkB;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,mBAAmB,EAAE,MAAM,CAAC;IAC5B,wBAAwB,EAAE,MAAM,CAAC;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,MAAM,CAAC,UAAU,EACtB,WAAW,EAAE,MAAM,GAClB,kBAAkB,CA0BpB;AAkCD,KAAK,YAAY,GAAG,CAClB,MAAM,EAAE,MAAM,EACd,IAAI,CAAC,EAAE,gBAAgB,KACpB,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAEnC,KAAK,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAG3C,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IAGxB,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IAEnB,cAAc,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CACrD;AA2GD,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,CAAC,UAAU,GACrB,MAAM,CA2BR;AA2ED,wBAAsB,GAAG,CAAC,IAAI,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CA0PhE;AAGD,YAAY,EAAE,KAAK,EAAE,CAAC"}

package/dist/lib/ec2-orchestrator.js

@@ -0,0 +1,469 @@
+// ec2-orchestrator — TS port of iteration-1's lib/ec2-orchestrator.sh.
+//
+// Entry point for the discovery → implementation → review state machine
+// running on a freshly bootstrapped EC2 worker. Phase markers,
+// CloudWatch-bound stdout/stderr, and the contract files under /tmp/ralph
+// are all preserved byte-identical to iteration 1.
+//
+// Public surface:
+//   run(opts) — full state machine. Returns an exit code (0/1/2/3) that
+//               the bin entry passes to process.exit.
+//   resolveOrchestratorConfig(env) — pure resolver, exposed for tests.
+//
+// Reads from env (set by the cloud-init bootstrap):
+//   RALPH_TARGET_REPO        owner/repo (required)
+//   RALPH_AWS_REGION         informational
+//   RALPH_WORK_DIR           absolute path to the fresh clone
+//   RALPH_DEFAULT_BRANCH     resolved default branch of the target repo
+//   RALPH_CONFIG             path to the validated .ralph/config.yaml
+//   RALPH_LAUNCH_TAG         per-launch identifier embedded in PR bodies
+//
+// With overridable defaults:
+//   RALPH_OUT_DIR                 /tmp/ralph
+//   RALPH_DISCOVERY_PROMPT        <package>/prompts/discovery.md
+//   RALPH_IMPLEMENTATION_PROMPT   <package>/prompts/implementation.md
+//   RALPH_REVIEW_PROMPT           <package>/prompts/review.md
+//   RALPH_REVIEW_WAIT_SEC         600
+//
+// Exit codes:
+//   0   discovery completed (NONE/ALL_BLOCKED) OR full chain completed
+//   1   claude invocation failed
+//   2   missing required env (target repo)
+//   3   contract violation (missing/invalid output, unknown status)
+import { readFileSync } from "node:fs";
+import { mkdir, readFile } from "node:fs/promises";
+import { dirname, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+import { runClaude } from "./claude-runner.js";
+import { parseDecision, parseImplResult, parseReviewResult, } from "./phase-result-schemas.js";
+import { render } from "./prompt-renderer.js";
+import { Emitter, outcome as outcomeMarker, pickedIssue as pickedIssueMarker, realClock, stdoutSink, } from "./structured-log-emitter.js";
+import { validate as validateTargetConfig, } from "./target-config-schema.js";
+export const MODULE_PREFIX = "ec2-orchestrator";
+export class OrchestratorError extends Error {
+    exitCode;
+    constructor(exitCode, message) {
+        super(message);
+        this.exitCode = exitCode;
+        this.name = "OrchestratorError";
+    }
+}
+const DEFAULT_REVIEW_WAIT_SEC = 600;
+const DEFAULT_OUT_DIR = "/tmp/ralph";
+export function resolveOrchestratorConfig(env, packageRoot) {
+    const targetRepo = env.RALPH_TARGET_REPO ?? "";
+    if (targetRepo.length === 0) {
+        throw new OrchestratorError(2, `${MODULE_PREFIX}: error: RALPH_TARGET_REPO is required`);
+    }
+    const promptsRoot = resolvePath(packageRoot, "prompts");
+    return {
+        targetRepo,
+        awsRegion: env.RALPH_AWS_REGION ?? "",
+        workDir: env.RALPH_WORK_DIR ?? "",
+        defaultBranch: env.RALPH_DEFAULT_BRANCH ?? "",
+        configPath: env.RALPH_CONFIG ?? "",
+        launchTag: env.RALPH_LAUNCH_TAG ?? "",
+        outDir: env.RALPH_OUT_DIR ?? DEFAULT_OUT_DIR,
+        discoveryPromptPath: env.RALPH_DISCOVERY_PROMPT ?? resolvePath(promptsRoot, "discovery.md"),
+        implementationPromptPath: env.RALPH_IMPLEMENTATION_PROMPT ??
+            resolvePath(promptsRoot, "implementation.md"),
+        reviewPromptPath: env.RALPH_REVIEW_PROMPT ?? resolvePath(promptsRoot, "review.md"),
+        reviewWaitSec: parseReviewWait(env.RALPH_REVIEW_WAIT_SEC),
+    };
+}
+function parseReviewWait(raw) {
+    if (!raw || raw.length === 0)
+        return DEFAULT_REVIEW_WAIT_SEC;
+    const n = Number.parseInt(raw, 10);
+    if (!Number.isFinite(n) || n < 0)
+        return DEFAULT_REVIEW_WAIT_SEC;
+    return n;
+}
+// loadTargetConfig — best-effort YAML read. Returns undefined when the
+// path is empty or the file is missing — the orchestrator emits empty
+// strings for the unresolved {{...}} keys in that case (matching the
+// bash port's `yq … // ""` fallback).
+async function loadTargetConfig(configPath) {
+    if (configPath.length === 0)
+        return undefined;
+    let raw;
+    try {
+        raw = await readFile(configPath, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+    try {
+        return validateTargetConfig(raw);
+    }
+    catch {
+        // We do not block the orchestrator on a malformed config — the
+        // operator's `ralph-validate-config` CLI is the authoritative gate.
+        // Empty values just leave the prompts with literal `{{KEY}}`
+        // placeholders, which is greppable in CloudWatch.
+        return undefined;
+    }
+}
+const realSleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const here = dirname(fileURLToPath(import.meta.url));
+// runSystemSetupDefault — invoke the OS-level cloud-init script that ships
+// inside the npm package at lib/cloud-init/system-setup.sh. Best-effort:
+// if the file is missing (running outside the published package, e.g. a
+// dev `tsx` invocation against the source tree), we no-op. The post-
+// condition the orchestrator depends on is "claude CLI + gh + repo clone
+// + .ralph/config.yaml validated" — operators who run from source are
+// expected to have set those up themselves.
+async function runSystemSetupDefault(workDir) {
+    const { spawn } = await import("node:child_process");
+    const candidates = [
+        // dist build → lib/cloud-init/system-setup.sh next to dist
+        resolvePath(here, "..", "..", "lib", "cloud-init", "system-setup.sh"),
+        // src tree
+        resolvePath(here, "..", "..", "..", "lib", "cloud-init", "system-setup.sh"),
+    ];
+    for (const path of candidates) {
+        try {
+            const { existsSync } = await import("node:fs");
+            if (!existsSync(path))
+                continue;
+            const child = spawn("bash", [path], {
+                stdio: "inherit",
+                cwd: workDir.length > 0 ? workDir : process.cwd(),
+                env: process.env,
+            });
+            const rc = await new Promise((res) => {
+                child.on("close", (code) => res(code ?? -1));
+                child.on("error", () => res(-1));
+            });
+            if (rc !== 0) {
+                throw new OrchestratorError(rc, `${MODULE_PREFIX}: system-setup.sh exited ${rc}`);
+            }
+            return;
+        }
+        catch (err) {
+            if (err instanceof OrchestratorError)
+                throw err;
+            // continue to the next candidate
+        }
+    }
+    // No system-setup.sh present — skip silently.
+}
+function buildDiscoveryContext(b) {
+    return {
+        RALPH_TARGET_REPO: b.config.targetRepo,
+        RALPH_DEFAULT_BRANCH: b.config.defaultBranch,
+        RALPH_WORK_DIR: b.config.workDir,
+        RALPH_BUILD_CMD: b.target?.build_cmd ?? "",
+        RALPH_TEST_CMD: b.target?.test_cmd ?? "",
+        RALPH_BRANCH_PREFIX: b.target?.branch_prefix ?? "",
+        PROMPT_EXTENSION: b.target?.prompt_extensions?.discovery ?? "",
+    };
+}
+function buildImplContext(b) {
+    return {
+        RALPH_TARGET_REPO: b.config.targetRepo,
+        RALPH_DEFAULT_BRANCH: b.config.defaultBranch,
+        RALPH_WORK_DIR: b.config.workDir,
+        RALPH_BUILD_CMD: b.target?.build_cmd ?? "",
+        RALPH_TEST_CMD: b.target?.test_cmd ?? "",
+        RALPH_BRANCH_PREFIX: b.target?.branch_prefix ?? "",
+        RALPH_AGENT_STUCK_LABEL: b.target?.agent_stuck_label ?? "agent-stuck",
+        RALPH_LAUNCH_TAG: b.config.launchTag,
+        PROMPT_EXTENSION: b.target?.prompt_extensions?.implementation ?? "",
+    };
+}
+function buildReviewContext(b, issue, pr, prBranch) {
+    return {
+        RALPH_TARGET_REPO: b.config.targetRepo,
+        RALPH_DEFAULT_BRANCH: b.config.defaultBranch,
+        RALPH_WORK_DIR: b.config.workDir,
+        RALPH_BUILD_CMD: b.target?.build_cmd ?? "",
+        RALPH_TEST_CMD: b.target?.test_cmd ?? "",
+        RALPH_ISSUE_NUMBER: String(issue),
+        RALPH_PR_NUMBER: String(pr),
+        RALPH_PR_BRANCH: prBranch,
+        RALPH_REVIEW_BOT_USERNAME: b.target?.review_bot.username ?? "",
+        RALPH_REVIEW_BOT_SOURCE: b.target?.review_bot.source ?? "",
+        PROMPT_EXTENSION: b.target?.prompt_extensions?.review ?? "",
+    };
+}
+function readContractText(path) {
+    return readFileSync(path, "utf8");
+}
+// mergeSetupEnvFile — reads a `KEY=VALUE` env file written by
+// system-setup.sh and merges it into the supplied env object. Missing
+// file is a no-op. Each line is trimmed; lines without `=` are skipped.
+// Values can be unquoted or wrapped in double quotes.
+export function mergeSetupEnvFile(path, env) {
+    let raw;
+    try {
+        raw = readFileSync(path, "utf8");
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    for (const rawLine of raw.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (line.length === 0 || line.startsWith("#"))
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            continue;
+        let value = line.slice(eq + 1);
+        if (value.length >= 2 &&
+            ((value.startsWith('"') && value.endsWith('"')) ||
+                (value.startsWith("'") && value.endsWith("'")))) {
+            value = value.slice(1, -1);
+        }
+        env[key] = value;
+        count += 1;
+    }
+    return count;
+}
+function readDecisionFile(outDir) {
+    return parseDecision(readContractText(resolvePath(outDir, "decision.json")));
+}
+function verifyDiscoveryOutputs(outDir) {
+    for (const f of [
+        "decision.json",
+        "issue.json",
+        "crafted-prompt.md",
+        "milestone-log.json",
+    ]) {
+        try {
+            readContractText(resolvePath(outDir, f));
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            throw new OrchestratorError(3, `${MODULE_PREFIX}: discovery did not write ${outDir}/${f}: ${detail}`);
+        }
+    }
+    // decision.json must parse — done via readDecisionFile when consumed.
+}
+function readImplFile(outDir) {
+    try {
+        return parseImplResult(readContractText(resolvePath(outDir, "impl-result.json")));
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new OrchestratorError(3, `${MODULE_PREFIX}: ${err.message}`);
+        }
+        throw err;
+    }
+}
+function readReviewFile(outDir) {
+    try {
+        return parseReviewResult(readContractText(resolvePath(outDir, "review-result.json")));
+    }
+    catch (err) {
+        if (err instanceof Error) {
+            throw new OrchestratorError(3, `${MODULE_PREFIX}: ${err.message}`);
+        }
+        throw err;
+    }
+}
+async function runClaudePhase(rendered, claude, startedAtMs) {
+    const r = await claude(rendered);
+    const elapsedSec = Math.floor((Date.now() - startedAtMs) / 1000);
+    return { exitCode: r.exitCode, durationSec: elapsedSec };
+}
+// run — full discovery → implementation → review state machine. Returns
+// the exit code that `ralph-orchestrate` should pass to process.exit.
+export async function run(opts = {}) {
+    const env = opts.env ?? process.env;
+    const sink = opts.sink ?? stdoutSink;
+    const clock = opts.clock ?? realClock;
+    const claude = opts.claude ?? runClaude;
+    const sleep = opts.sleep ?? realSleep;
+    const packageRoot = opts.packageRoot ?? resolvePath(here, "..", "..");
+    let config;
+    try {
+        config = resolveOrchestratorConfig(env, packageRoot);
+    }
+    catch (err) {
+        if (err instanceof OrchestratorError) {
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        throw err;
+    }
+    const info = (line) => sink(`${MODULE_PREFIX}: ${line}`);
+    info("ralph-harness orchestrator");
+    info(`target=${config.targetRepo} work_dir=${config.workDir} default_branch=${config.defaultBranch} config=${config.configPath} out=${config.outDir} launch_tag=${config.launchTag}`);
+    await mkdir(config.outDir, { recursive: true });
+    const runSystemSetup = opts.runSystemSetup ?? runSystemSetupDefault;
+    await runSystemSetup(config.workDir);
+    // system-setup.sh writes RALPH_WORK_DIR / RALPH_DEFAULT_BRANCH /
+    // RALPH_CONFIG / RALPH_LAUNCH_TAG into /tmp/ralph/setup.env (one
+    // KEY=VALUE per line). Merge those values into env so the rest of the
+    // orchestrator sees them. We re-resolve the config afterwards.
+    mergeSetupEnvFile(resolvePath(config.outDir, "setup.env"), env);
+    config = resolveOrchestratorConfig(env, packageRoot);
+    const target = await loadTargetConfig(config.configPath);
+    const bundle = { config, target };
+    const emitter = new Emitter(sink, clock);
+    // ---- Discovery ----
+    const discoveryTemplate = await readFile(config.discoveryPromptPath, "utf8");
+    const discoveryRendered = render(discoveryTemplate, buildDiscoveryContext(bundle));
+    emitter.start({ phase: "discovery", target: config.targetRepo });
+    const discoveryStart = Date.now();
+    const discoveryResult = await runClaudePhase(discoveryRendered, claude, discoveryStart);
+    emitter.end({
+        phase: "discovery",
+        durationSec: discoveryResult.durationSec,
+    });
+    if (discoveryResult.exitCode !== 0) {
+        process.stderr.write(`${MODULE_PREFIX}: error: claude discovery exited ${discoveryResult.exitCode}\n`);
+        return 1;
+    }
+    try {
+        verifyDiscoveryOutputs(config.outDir);
+    }
+    catch (err) {
+        if (err instanceof OrchestratorError) {
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        throw err;
+    }
+    let decision;
+    try {
+        decision = readDecisionFile(config.outDir);
+    }
+    catch (err) {
+        process.stderr.write(`${MODULE_PREFIX}: error: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 3;
+    }
+    if (decision.status === "NONE") {
+        info("discovery returned NONE — no eligible candidates");
+        sink(outcomeMarker({ kind: "no_work" }));
+        return 0;
+    }
+    if (decision.status === "ALL_BLOCKED") {
+        info("discovery returned ALL_BLOCKED — every candidate has unsatisfied blockers");
+        sink(outcomeMarker({ kind: "all_blocked" }));
+        return 0;
+    }
+    // PICKED branch
+    const issue = decision.issue;
+    info(`discovery picked issue #${issue}`);
+    sink(pickedIssueMarker(issue));
+    // ---- Implementation ----
+    const implTemplate = await readFile(config.implementationPromptPath, "utf8");
+    const craftedPath = resolvePath(config.outDir, "crafted-prompt.md");
+    let crafted;
+    try {
+        crafted = await readFile(craftedPath, "utf8");
+    }
+    catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`${MODULE_PREFIX}: error: crafted-prompt.md not found: ${detail}\n`);
+        return 3;
+    }
+    const implRendered = `${render(implTemplate, buildImplContext(bundle))}\n\n---\n\n## Crafted context from discovery\n\n${crafted}`;
+    emitter.start({ phase: "implementation", issue });
+    const implStart = Date.now();
+    const implResult = await runClaudePhase(implRendered, claude, implStart);
+    let impl;
+    try {
+        impl = readImplFile(config.outDir);
+    }
+    catch (err) {
+        if (err instanceof OrchestratorError) {
+            // We still want to emit the PHASE_END marker before bailing, with
+            // status=unknown.
+            emitter.end({
+                phase: "implementation",
+                durationSec: implResult.durationSec,
+                issue,
+                status: "unknown",
+            });
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        throw err;
+    }
+    emitter.end({
+        phase: "implementation",
+        durationSec: implResult.durationSec,
+        issue,
+        status: impl.status,
+    });
+    if (implResult.exitCode !== 0) {
+        process.stderr.write(`${MODULE_PREFIX}: error: claude implementation exited ${implResult.exitCode}\n`);
+        return 1;
+    }
+    if (impl.status === "AGENT_STUCK") {
+        info(`implementation reported agent_stuck for issue #${issue}`);
+        sink(outcomeMarker({ kind: "agent_stuck", issue }));
+        return 0;
+    }
+    // PR_OPENED branch
+    const prNumber = impl.pr_number;
+    const prBranch = impl.branch;
+    info(`implementation opened PR #${prNumber} for issue #${issue}`);
+    // ---- Review ----
+    if (config.reviewWaitSec > 0) {
+        info(`review: sleeping ${config.reviewWaitSec}s for review bot window`);
+        await sleep(config.reviewWaitSec * 1_000);
+    }
+    const reviewTemplate = await readFile(config.reviewPromptPath, "utf8");
+    const reviewRendered = render(reviewTemplate, buildReviewContext(bundle, issue, prNumber, prBranch));
+    emitter.start({ phase: "review", issue, pr: prNumber });
+    const reviewStart = Date.now();
+    const reviewResult = await runClaudePhase(reviewRendered, claude, reviewStart);
+    let review;
+    try {
+        review = readReviewFile(config.outDir);
+    }
+    catch (err) {
+        if (err instanceof OrchestratorError) {
+            emitter.end({
+                phase: "review",
+                durationSec: reviewResult.durationSec,
+                issue,
+                pr: prNumber,
+                status: "unknown",
+            });
+            process.stderr.write(`${err.message}\n`);
+            return err.exitCode;
+        }
+        throw err;
+    }
+    emitter.end({
+        phase: "review",
+        durationSec: reviewResult.durationSec,
+        issue,
+        pr: prNumber,
+        status: review.status,
+    });
+    if (reviewResult.exitCode !== 0) {
+        process.stderr.write(`${MODULE_PREFIX}: error: claude review exited ${reviewResult.exitCode}\n`);
+        return 1;
+    }
+    if (review.status === "NO_REVIEW") {
+        info("review: no verdict from configured review bot; no caveman log appended");
+        sink(outcomeMarker({
+            kind: "pr_opened",
+            issue,
+            pr: prNumber,
+            review: "none",
+        }));
+        return 0;
+    }
+    // REVISION_APPLIED → caveman log append handled by the review call's
+    // own exit (slice 9 contract). The orchestrator just records the OUTCOME.
+    info(`review: revision applied to PR #${prNumber}`);
+    sink(outcomeMarker({
+        kind: "pr_opened",
+        issue,
+        pr: prNumber,
+        review: "revised",
+    }));
+    return 0;
+}
+//# sourceMappingURL=ec2-orchestrator.js.map