@unimatrix27/ralph-harness 1.0.0

package/dist/lib/target-config-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"target-config-schema.js","sourceRoot":"","sources":["../../src/lib/target-config-schema.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,EAAE;AACF,4EAA4E;AAC5E,+DAA+D;AAC/D,kEAAkE;AAClE,uFAAuF;AACvF,sBAAsB;AACtB,8BAA8B;AAC9B,qBAAqB;AACrB,mCAAmC;AACnC,6EAA6E;AAC7E,EAAE;AACF,qCAAqC;AAErC,OAAO,EAAE,KAAK,IAAI,SAAS,EAAE,MAAM,MAAM,CAAC;AAC1C,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,aAAa,GAAG,sBAAsB,CAAC;AAI7C,MAAM,OAAO,aAAc,SAAQ,KAAK;IAEpB;IADlB,YACkB,IAAsB,EACtC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAkB;QAItC,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;IAC9B,CAAC;CACF;AAED,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;AAEzC,MAAM,eAAe,GAAG,CAAC;KACtB,MAAM,CAAC;IACN,QAAQ,EAAE,cAAc;IACxB,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;CACtC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,sBAAsB,GAAG,CAAC;KAC7B,MAAM,CAAC;IACN,SAAS,EAAE,cAAc,CAAC,QAAQ,EAAE;IACpC,cAAc,EAAE,cAAc,CAAC,QAAQ,EAAE;IACzC,MAAM,EAAE,cAAc,CAAC,QAAQ,EAAE;CAClC,CAAC;KACD,MAAM,EAAE,CAAC;AAEZ,MAAM,kBAAkB,GAAG,cAAc,CAAC,MAAM,CAC9C,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,EACxC,EAAE,OAAO,EAAE,kDAAkD,EAAE,CAChE,CAAC;AAEF,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC;KAChC,MAAM,CAAC;IACN,SAAS,EAAE,cAAc;IACzB,QAAQ,EAAE,cAAc;IACxB,aAAa,EAAE,kBAAkB;IACjC,UAAU,EAAE,eAAe;IAC3B,iBAAiB,EAAE,cAAc,CAAC,QAAQ,EAAE;IAC5C,iBAAiB,EAAE,sBAAsB,CAAC,QAAQ,EAAE;CACrD,CAAC;KACD,MAAM,EAAE,CAAC;AAIZ,MAAM,UAAU,QAAQ,CAAC,UAAkB;IACzC,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,SAAS,CAAC,UAAU,EAAE,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,CAAC;IAC1D,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAChE,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,mBAAmB,MAAM,EAAE,CAAC,CAAC;IAC1D,CAAC;IAED,IAAI,MAAM,KAAK,IAAI,IAAI,MAAM,KAAK,SAAS,EAAE,CAAC;QAC5C,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,wCAAwC,CAAC,CAAC;IACvE,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QACxD,MAAM,GAAG,GAAG,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,MAAM,CAAC;QAC5D,MAAM,IAAI,aAAa,CAAC,CAAC,EAAE,oCAAoC,GAAG,EAAE,CAAC,CAAC;IACxE,CAAC;IAED,MAAM,MAAM,GAAG,kBAAkB,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACpD,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,MAAM,CAAC,IAAI,CAAC;IAEvC,MAAM,oBAAoB,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AACnD,CAAC;AAED,SAAS,oBAAoB,CAC3B,GAAe,EACf,KAAc;IAEd,yEAAyE;IACzE,qEAAqE;IACrE,0EAA0E;IAC1E,oCAAoC;IACpC,MAAM,MAAM,GAAG,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CACjC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,GAAG,SAAS,CAAC,CAAC,EAAE,KAAK,CAAC,CACpD,CAAC;IACF,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAE,CAAC;IACzB,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACpC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IAE5D,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB,EAAE,CAAC;QACvC,MAAM,IAAI,GAAI,KAAwC,CAAC,IAAI,IAAI,EAAE,CAAC;QAClE,MAAM,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,WAAW,CAAC;QACnC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,IAAI,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QAC5D,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,kBAAkB,OAAO,EAAE,CAAC,CAAC;IAC3D,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;QAClC,MAAM,QAAQ,GACX,KAA0C,CAAC,QAAQ,IAAI,aAAa,CAAC;QACxE,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;YACnC,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,2BAA2B,OAAO,EAAE,CAAC,CAAC;QACpE,CAAC;QACD,MAAM,GAAG,GAAG,YAAY,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC,CAAC;QAC5C,OAAO,IAAI,aAAa,CACtB,CAAC,EACD,GAAG,OAAO,cAAc,QAAQ,SAAS,GAAG,EAAE,CAC/C,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,WAAW,IAAI,KAAK,CAAC,IAAI,KAAK,SAAS,EAAE,CAAC;QAC3D,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,GAAG,OAAO,6BAA6B,CAAC,CAAC;IACvE,CAAC;IAED,gFAAgF;IAChF,IACG,KAAK,CAAC,IAAe,KAAK,eAAe;QACzC,KAAK,CAAC,IAAe,KAAK,oBAAoB,EAC/C,CAAC;QACD,MAAM,IAAI,GACP,KAAqD,CAAC,OAAO;YAC7D,KAAoD,CAAC,MAAM;YAC5D,EAAE,CAAC;QACL,MAAM,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC/D,MAAM,QAAQ,GAAI,KAA2C,CAAC,QAAQ,CAAC;QACvE,OAAO,IAAI,aAAa,CACtB,CAAC,EACD,GAAG,OAAO,YAAY,OAAO,IAAI,eAAe,UAAU,cAAc,CAAC,QAAQ,CAAC,GAAG,CACtF,CAAC;IACJ,CAAC;IAED,IAAI,KAAK,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC5B,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,GAAG,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;IAC9D,CAAC;IAED,OAAO,IAAI,aAAa,CAAC,CAAC,EAAE,GAAG,OAAO,KAAK,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,SAAS,SAAS,CAAC,KAAiB,EAAE,KAAc;IAClD,kFAAkF;IAClF,IAAI,KAAK,CAAC,IAAI,KAAK,mBAAmB;QAAE,OAAO,CAAC,CAAC;IACjD,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC9E,OAAO,CAAC,CAAC;AACX,CAAC;AAED,SAAS,UAAU,CAAC,KAAc,EAAE,IAA4B;IAC9D,IAAI,GAAG,GAAY,KAAK,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QAC/E,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;YAAE,OAAO,KAAK,CAAC;QAChE,GAAG,GAAI,GAA+B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,YAAY,CAAC,KAAc,EAAE,IAA4B;IAChE,IAAI,GAAG,GAAY,KAAK,CAAC;IACzB,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;QACrB,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS,IAAI,OAAO,GAAG,KAAK,QAAQ;YAAE,OAAO,WAAW,CAAC;QACrF,GAAG,GAAI,GAA+B,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;IACpD,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC;QAAE,OAAO,OAAO,CAAC;IACvC,IAAI,GAAG,KAAK,IAAI;QAAE,OAAO,MAAM,CAAC;IAChC,OAAO,OAAO,GAAG,CAAC;AACpB,CAAC;AAED,SAAS,cAAc,CAAC,QAAiB;IACvC,IAAI,QAAQ,KAAK,SAAS;QAAE,OAAO,WAAW,CAAC;IAC/C,IAAI,OAAO,QAAQ,KAAK,QAAQ;QAAE,OAAO,QAAQ,CAAC;IAClD,OAAO,MAAM,CAAC,QAAQ,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAe;IACvC,OAAO,GAAG,aAAa,YAAY,OAAO,EAAE,CAAC;AAC/C,CAAC"}

package/dist/lib/user-data-renderer.d.ts

@@ -0,0 +1,20 @@
+export declare const MODULE_PREFIX = "user-data-renderer";
+export declare const USER_DATA_CAP_BYTES = 16384;
+export declare class RawSizeExceededError extends Error {
+    readonly bytes: number;
+    constructor(bytes: number);
+}
+export interface UserDataInput {
+    targetRepo: string;
+    harnessVersion: string;
+    awsRegion: string;
+    logGroup: string;
+    githubTokenSsmKey: string;
+    claudeOauthSsmKey: string;
+    agentStuckLabel: string;
+    extraEnv?: Readonly<Record<string, string>>;
+    packageName?: string;
+}
+export declare function shellSingleQuote(value: string): string;
+export declare function renderUserData(input: UserDataInput): string;
+//# sourceMappingURL=user-data-renderer.d.ts.map

package/dist/lib/user-data-renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-data-renderer.d.ts","sourceRoot":"","sources":["../../src/lib/user-data-renderer.ts"],"names":[],"mappings":"AAoBA,eAAO,MAAM,aAAa,uBAAuB,CAAC;AAIlD,eAAO,MAAM,mBAAmB,QAAS,CAAC;AAE1C,qBAAa,oBAAqB,SAAQ,KAAK;aACjB,KAAK,EAAE,MAAM;gBAAb,KAAK,EAAE,MAAM;CAM1C;AAED,MAAM,WAAW,aAAa;IAE5B,UAAU,EAAE,MAAM,CAAC;IACnB,cAAc,EAAE,MAAM,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,MAAM,CAAC;IACjB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IAGxB,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAG5C,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAOD,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED,wBAAgB,cAAc,CAAC,KAAK,EAAE,aAAa,GAAG,MAAM,CAqC3D"}

package/dist/lib/user-data-renderer.js

@@ -0,0 +1,75 @@
+// user-data-renderer — renders the small inline bash stub that EC2 receives
+// as user-data. Iteration 1 bundled the entire bash harness (`fire-launcher`
+// + `ec2-orchestrator` + `cloud-init/bootstrap`) inline, which forced gzip
+// compression to fit under the 16 KiB cap. Iteration 2 ships the harness via
+// npm; the user-data shrinks to ~15 lines that install Node 24, install the
+// harness package, then `exec ralph-orchestrate`.
+//
+// Cap-check: EC2's user-data cap is 16,384 bytes on the *raw* decoded
+// payload — NOT on the base64 wire form, NOT on the gzipped bytes. PR #20
+// and #21 (iteration 1) checked the gzipped size against this dimension,
+// which let oversized payloads slip through when gzip happened to compress
+// well. We check the raw rendered bytes here; the new stub is well under
+// the cap so a `RawSizeExceeded` throw should be the equivalent of an
+// assertion failure rather than a regular operating condition.
+//
+// Public surface:
+//   renderUserData(input)        — returns the rendered bash string
+//   USER_DATA_CAP_BYTES          — the EC2 16 KiB cap (raw bytes)
+//   RawSizeExceededError         — thrown when the rendered output exceeds the cap
+export const MODULE_PREFIX = "user-data-renderer";
+// EC2 caps user-data at 16,384 raw decoded bytes. cf.
+// docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html
+export const USER_DATA_CAP_BYTES = 16_384;
+export class RawSizeExceededError extends Error {
+    bytes;
+    constructor(bytes) {
+        super(`${MODULE_PREFIX}: rendered user-data is ${bytes} bytes, exceeds the EC2 cap of ${USER_DATA_CAP_BYTES} raw bytes`);
+        this.bytes = bytes;
+        this.name = "RawSizeExceededError";
+    }
+}
+const DEFAULT_PACKAGE_NAME = "@unimatrix27/ralph-harness";
+// shellSingleQuote — wrap a value in POSIX single quotes, escaping any
+// embedded `'` as `'\''`. Single-quoted strings are safe against every
+// other shell metacharacter.
+export function shellSingleQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+export function renderUserData(input) {
+    const pkg = input.packageName ?? DEFAULT_PACKAGE_NAME;
+    // Build the export block deterministically — sorted keys keep the
+    // snapshot test stable across object literal reorders.
+    const baseEnv = {
+        RALPH_TARGET_REPO: input.targetRepo,
+        RALPH_AWS_REGION: input.awsRegion,
+        RALPH_LOG_GROUP: input.logGroup,
+        RALPH_GITHUB_TOKEN_SSM_KEY: input.githubTokenSsmKey,
+        RALPH_CLAUDE_OAUTH_SSM_KEY: input.claudeOauthSsmKey,
+        RALPH_AGENT_STUCK_LABEL: input.agentStuckLabel,
+        RALPH_HARNESS_VERSION: input.harnessVersion,
+    };
+    const merged = { ...baseEnv, ...(input.extraEnv ?? {}) };
+    const sortedKeys = Object.keys(merged).sort();
+    const exports = sortedKeys
+        .map((k) => `export ${k}=${shellSingleQuote(merged[k])}`)
+        .join("\n");
+    // 15-line target — keep this tight. Anything heavyweight goes in
+    // `lib/cloud-init/system-setup.sh` (shipped inside the npm package and
+    // invoked by `ralph-orchestrate` as its first step).
+    const stub = `#!/bin/bash
+set -euo pipefail
+exec > >(tee -a /var/log/ralph-user-data.log) 2>&1
+${exports}
+curl -fsSL https://rpm.nodesource.com/setup_24.x | bash -
+dnf install -y nodejs git jq awscli
+npm install -g ${pkg}@${input.harnessVersion}
+exec ralph-orchestrate
+`;
+    const bytes = Buffer.byteLength(stub, "utf8");
+    if (bytes > USER_DATA_CAP_BYTES) {
+        throw new RawSizeExceededError(bytes);
+    }
+    return stub;
+}
+//# sourceMappingURL=user-data-renderer.js.map

package/dist/lib/user-data-renderer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"user-data-renderer.js","sourceRoot":"","sources":["../../src/lib/user-data-renderer.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,6EAA6E;AAC7E,2EAA2E;AAC3E,6EAA6E;AAC7E,4EAA4E;AAC5E,kDAAkD;AAClD,EAAE;AACF,sEAAsE;AACtE,0EAA0E;AAC1E,yEAAyE;AACzE,2EAA2E;AAC3E,yEAAyE;AACzE,sEAAsE;AACtE,+DAA+D;AAC/D,EAAE;AACF,kBAAkB;AAClB,oEAAoE;AACpE,kEAAkE;AAClE,mFAAmF;AAEnF,MAAM,CAAC,MAAM,aAAa,GAAG,oBAAoB,CAAC;AAElD,sDAAsD;AACtD,6DAA6D;AAC7D,MAAM,CAAC,MAAM,mBAAmB,GAAG,MAAM,CAAC;AAE1C,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACjB;IAA5B,YAA4B,KAAa;QACvC,KAAK,CACH,GAAG,aAAa,2BAA2B,KAAK,kCAAkC,mBAAmB,YAAY,CAClH,CAAC;QAHwB,UAAK,GAAL,KAAK,CAAQ;QAIvC,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;IACrC,CAAC;CACF;AAmBD,MAAM,oBAAoB,GAAG,4BAA4B,CAAC;AAE1D,uEAAuE;AACvE,uEAAuE;AACvE,6BAA6B;AAC7B,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,GAAG,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,KAAoB;IACjD,MAAM,GAAG,GAAG,KAAK,CAAC,WAAW,IAAI,oBAAoB,CAAC;IACtD,kEAAkE;IAClE,uDAAuD;IACvD,MAAM,OAAO,GAA2B;QACtC,iBAAiB,EAAE,KAAK,CAAC,UAAU;QACnC,gBAAgB,EAAE,KAAK,CAAC,SAAS;QACjC,eAAe,EAAE,KAAK,CAAC,QAAQ;QAC/B,0BAA0B,EAAE,KAAK,CAAC,iBAAiB;QACnD,0BAA0B,EAAE,KAAK,CAAC,iBAAiB;QACnD,uBAAuB,EAAE,KAAK,CAAC,eAAe;QAC9C,qBAAqB,EAAE,KAAK,CAAC,cAAc;KAC5C,CAAC;IACF,MAAM,MAAM,GAA2B,EAAE,GAAG,OAAO,EAAE,GAAG,CAAC,KAAK,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,CAAC;IACjF,MAAM,UAAU,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,CAAC;IAC9C,MAAM,OAAO,GAAG,UAAU;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,IAAI,gBAAgB,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,EAAE,CAAC;SACzD,IAAI,CAAC,IAAI,CAAC,CAAC;IAEd,iEAAiE;IACjE,uEAAuE;IACvE,qDAAqD;IACrD,MAAM,IAAI,GAAG;;;EAGb,OAAO;;;iBAGQ,GAAG,IAAI,KAAK,CAAC,cAAc;;CAE3C,CAAC;IAEA,MAAM,KAAK,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC9C,IAAI,KAAK,GAAG,mBAAmB,EAAE,CAAC;QAChC,MAAM,IAAI,oBAAoB,CAAC,KAAK,CAAC,CAAC;IACxC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/cloud-init/system-setup.sh

@@ -0,0 +1,338 @@
+#!/usr/bin/env bash
+#
+# system-setup.sh — slice 5 OS-level setup. Runs as the first step of
+# `ralph-orchestrate` on the EC2 worker, AFTER the user-data stub has
+# installed Node + git + jq + awscli + the harness package.
+#
+# Scope (intentionally OS-level only — everything else is in TS):
+#   1. start the amazon-cloudwatch-agent so /var/log/ralph.log streams
+#      live to CloudWatch (every ~5s) — survives force-termination
+#   2. install gh, .NET 10 SDK, Docker, and the claude CLI
+#   3. fetch GitHub PAT and Claude OAuth credential from SSM SecureString
+#      into mode-0600 files
+#   4. clone the target repo on its resolved default branch
+#   5. safety guards (default branch, clean working tree, origin matches
+#      RALPH_TARGET_REPO)
+#   6. configure claude MCPs (serena, morph-mcp, context7, github,
+#      sequential-thinking; `memory` excluded)
+#   7. validate .ralph/config.yaml via `ralph-validate-config`
+#   8. write RALPH_WORK_DIR / RALPH_DEFAULT_BRANCH / RALPH_CONFIG /
+#      RALPH_LAUNCH_TAG to /tmp/ralph/setup.env so the TS orchestrator
+#      picks them up after this subprocess exits
+#
+# Inputs (env, set by ralph-fire's user-data stub):
+#   RALPH_TARGET_REPO            required, owner/repo
+#   RALPH_AWS_REGION             required, e.g. eu-central-1
+#   RALPH_GITHUB_TOKEN_SSM_KEY   SSM SecureString name for the GitHub PAT
+#   RALPH_CLAUDE_OAUTH_SSM_KEY   SSM SecureString name for the OAuth cred
+#   RALPH_LOG_GROUP              CloudWatch log group
+#
+# Output: /tmp/ralph/setup.env (KEY=VALUE per line) — read by ralph-orchestrate
+# after this script exits.
+
+set -uo pipefail
+
+: "${HOME:=/root}"
+export HOME
+
+# claude CLI refuses --permission-mode bypassPermissions when running as
+# root unless IS_SANDBOX=1. cloud-init runs as root and the orchestrator
+# needs the bypass. The throwaway EC2 (scoped IAM, no SSH, ≤75-min
+# lifetime) is the sandbox this knob exists for.
+export IS_SANDBOX=1
+
+: "${RALPH_LOG_GROUP:=/ralph/main}"
+: "${RALPH_GITHUB_TOKEN_SSM_KEY:=/ralph/github-pat}"
+: "${RALPH_CLAUDE_OAUTH_SSM_KEY:=/ralph/claude-oauth-credential}"
+
+LOG_FILE="/var/log/ralph.log"
+: > "$LOG_FILE" 2>/dev/null || true
+
+# ---- IMDSv2 + metadata -------------------------------------------------------
+
+setup__md_token=$(curl -fsS -m 5 -X PUT \
+    "http://169.254.169.254/latest/api/token" \
+    -H "X-aws-ec2-metadata-token-ttl-seconds: 21600" 2>/dev/null || true)
+
+setup__md() {
+    curl -fsS -m 5 \
+        -H "X-aws-ec2-metadata-token: ${setup__md_token}" \
+        "http://169.254.169.254/latest/meta-data/$1" 2>/dev/null || true
+}
+
+INSTANCE_ID=$(setup__md instance-id)
+REGION="${RALPH_AWS_REGION:-$(setup__md placement/region)}"
+LOG_STREAM="${INSTANCE_ID:-unknown-instance}"
+
+# Per-launch identifier embedded by the implementation call as an HTML
+# comment in the PR body so the launcher can correlate post-hoc when the
+# instance was hard-killed before recording state. Defaults to the
+# instance id; falls back to a timestamp+pid pair if IMDS is unreachable.
+RALPH_LAUNCH_TAG="${INSTANCE_ID:-$(date -u +%s)-$$}"
+export RALPH_LAUNCH_TAG
+
+setup__info() { printf 'system-setup: %s\n' "$*"; }
+setup__err()  { printf 'system-setup: error: %s\n' "$*" >&2; }
+
+# Pulls a SecureString parameter, decrypts under the role's permitted KMS
+# alias, prints the value to stdout. Caller redirects to a 0600 file.
+setup__ssm_get() {
+    local name="$1"
+    aws --region "$REGION" ssm get-parameter \
+        --name "$name" \
+        --with-decryption \
+        --query 'Parameter.Value' \
+        --output text
+}
+
+# ---- live log streaming via amazon-cloudwatch-agent --------------------------
+
+setup__start_cwagent() {
+    setup__info "PHASE_START phase=cwagent stream=${LOG_STREAM}"
+    if ! dnf -y -q --allowerasing install amazon-cloudwatch-agent >/dev/null 2>&1; then
+        setup__err "amazon-cloudwatch-agent install failed; live log streaming disabled"
+        return 0
+    fi
+    local cfg=/opt/aws/amazon-cloudwatch-agent/etc/amazon-cloudwatch-agent.d/ralph.json
+    install -d -m 755 "$(dirname "$cfg")"
+    cat > "$cfg" <<JSON
+{
+  "agent": { "run_as_user": "root" },
+  "logs": {
+    "force_flush_interval": 5,
+    "logs_collected": {
+      "files": {
+        "collect_list": [
+          {
+            "file_path": "${LOG_FILE}",
+            "log_group_name": "${RALPH_LOG_GROUP}",
+            "log_stream_name": "${LOG_STREAM}",
+            "timezone": "UTC"
+          },
+          {
+            "file_path": "/var/log/cloud-init-output.log",
+            "log_group_name": "${RALPH_LOG_GROUP}",
+            "log_stream_name": "${LOG_STREAM}-cloud-init",
+            "timezone": "UTC"
+          }
+        ]
+      }
+    }
+  }
+}
+JSON
+    if /opt/aws/amazon-cloudwatch-agent/bin/amazon-cloudwatch-agent-ctl \
+            -a fetch-config -m ec2 -c "file:${cfg}" -s >/dev/null 2>&1; then
+        setup__info "PHASE_END phase=cwagent"
+    else
+        setup__err "amazon-cloudwatch-agent failed to start; live log streaming disabled"
+    fi
+}
+
+# ---- install OS deps (gh, .NET 10, Docker, claude) ---------------------------
+
+setup__install_deps() {
+    setup__info "PHASE_START phase=install-deps"
+
+    # gh CLI — official rpm repo.
+    dnf -y -q config-manager --add-repo \
+        https://cli.github.com/packages/rpm/gh-cli.repo >/dev/null
+    dnf -y -q --allowerasing install gh >/dev/null
+
+    # Docker — required by the github MCP container.
+    dnf -y -q --allowerasing install docker >/dev/null
+    systemctl enable --now docker >/dev/null 2>&1 || true
+
+    # uv (astral) — used by serena.
+    if ! command -v uv >/dev/null 2>&1; then
+        curl -LsSf https://astral.sh/uv/install.sh | sh >/dev/null 2>&1 || true
+        export PATH="/root/.local/bin:${HOME}/.local/bin:${PATH}"
+    fi
+
+    # .NET 10 SDK via dotnet-install.sh.
+    if ! command -v dotnet >/dev/null 2>&1; then
+        curl -fsSL https://dot.net/v1/dotnet-install.sh -o /tmp/dotnet-install.sh
+        chmod +x /tmp/dotnet-install.sh
+        /tmp/dotnet-install.sh --channel 10.0 \
+            --install-dir /usr/share/dotnet >/dev/null
+        ln -sf /usr/share/dotnet/dotnet /usr/local/bin/dotnet
+        rm -f /tmp/dotnet-install.sh
+    fi
+
+    # claude CLI (npm global).
+    npm install -g @anthropic-ai/claude-code >/dev/null
+
+    setup__info "PHASE_END phase=install-deps"
+}
+
+# ---- fetch secrets from SSM --------------------------------------------------
+
+setup__fetch_secrets() {
+    setup__info "PHASE_START phase=fetch-secrets"
+
+    local pat_dir="${HOME}/.ralph"
+    install -d -m 700 "$pat_dir"
+    local pat_file="${pat_dir}/github-pat"
+    if ! setup__ssm_get "$RALPH_GITHUB_TOKEN_SSM_KEY" > "$pat_file"; then
+        setup__err "could not fetch GitHub PAT from ${RALPH_GITHUB_TOKEN_SSM_KEY}"
+        return 1
+    fi
+    chmod 600 "$pat_file"
+    if ! gh auth login --with-token < "$pat_file" >/dev/null 2>&1; then
+        setup__err "gh auth login failed"
+        return 1
+    fi
+    if ! gh auth setup-git >/dev/null 2>&1; then
+        setup__err "gh auth setup-git failed"
+        return 1
+    fi
+    GH_TOKEN="$(<"$pat_file")"
+    GITHUB_PERSONAL_ACCESS_TOKEN="$GH_TOKEN"
+    export GH_TOKEN GITHUB_PERSONAL_ACCESS_TOKEN
+
+    local cred_dir="${HOME}/.claude"
+    install -d -m 700 "$cred_dir"
+    local cred_file="${cred_dir}/.credentials.json"
+    if ! setup__ssm_get "$RALPH_CLAUDE_OAUTH_SSM_KEY" > "$cred_file"; then
+        setup__err "could not fetch OAuth credential from ${RALPH_CLAUDE_OAUTH_SSM_KEY}"
+        return 1
+    fi
+    chmod 600 "$cred_file"
+
+    setup__info "PHASE_END phase=fetch-secrets"
+}
+
+# ---- fresh clone of target on resolved default branch ------------------------
+
+setup__clone_target() {
+    setup__info "PHASE_START phase=clone-target target=${RALPH_TARGET_REPO}"
+    if [[ -z "${RALPH_TARGET_REPO:-}" ]]; then
+        setup__err "RALPH_TARGET_REPO is required"
+        return 2
+    fi
+    local default_branch
+    default_branch=$(gh repo view "$RALPH_TARGET_REPO" \
+        --json defaultBranchRef \
+        --jq '.defaultBranchRef.name')
+    if [[ -z "$default_branch" ]]; then
+        setup__err "could not resolve default branch for ${RALPH_TARGET_REPO}"
+        return 1
+    fi
+    local work_dir
+    work_dir="$(mktemp -d -t ralph-work-XXXXXX)"
+    if ! git clone --depth 1 --branch "$default_branch" \
+            "https://github.com/${RALPH_TARGET_REPO}.git" "$work_dir" \
+            >/dev/null 2>&1; then
+        setup__err "git clone of ${RALPH_TARGET_REPO} failed"
+        return 1
+    fi
+    RALPH_WORK_DIR="$work_dir"
+    RALPH_DEFAULT_BRANCH="$default_branch"
+    export RALPH_WORK_DIR RALPH_DEFAULT_BRANCH
+    cd "$RALPH_WORK_DIR"
+    setup__info "PHASE_END phase=clone-target branch=${default_branch} dir=${RALPH_WORK_DIR}"
+}
+
+# ---- safety guards -----------------------------------------------------------
+
+setup__safety_guards() {
+    setup__info "PHASE_START phase=safety-guards"
+    cd "${RALPH_WORK_DIR:?work dir required}"
+
+    local current_branch
+    current_branch=$(git rev-parse --abbrev-ref HEAD)
+    if [[ "$current_branch" != "$RALPH_DEFAULT_BRANCH" ]]; then
+        setup__err "post-clone branch is ${current_branch}, expected ${RALPH_DEFAULT_BRANCH}"
+        return 1
+    fi
+
+    if [[ -n "$(git status --porcelain)" ]]; then
+        setup__err "fresh clone has uncommitted state — refusing to continue"
+        return 1
+    fi
+
+    local origin
+    origin=$(git remote get-url origin)
+    if [[ "$origin" != *"${RALPH_TARGET_REPO}"* ]]; then
+        setup__err "origin (${origin}) does not match RALPH_TARGET_REPO (${RALPH_TARGET_REPO})"
+        return 1
+    fi
+
+    setup__info "PHASE_END phase=safety-guards"
+}
+
+# ---- configure claude MCPs (memory excluded) ---------------------------------
+
+setup__configure_mcps() {
+    setup__info "PHASE_START phase=configure-mcps"
+    claude mcp add serena -- \
+        uvx --from git+https://github.com/oraios/serena serena-mcp-server \
+        >/dev/null 2>&1 || true
+    claude mcp add morph-mcp -- \
+        npx -y @morph-labs/morph-mcp \
+        >/dev/null 2>&1 || true
+    claude mcp add context7 -- \
+        npx -y @upstash/context7-mcp \
+        >/dev/null 2>&1 || true
+    claude mcp add github -- \
+        docker run -i --rm \
+            -e GITHUB_PERSONAL_ACCESS_TOKEN \
+            ghcr.io/github/github-mcp-server \
+        >/dev/null 2>&1 || true
+    claude mcp add sequential-thinking -- \
+        npx -y @modelcontextprotocol/server-sequential-thinking \
+        >/dev/null 2>&1 || true
+    setup__info "PHASE_END phase=configure-mcps"
+}
+
+# ---- validate target config via ralph-validate-config ------------------------
+
+setup__validate_config() {
+    setup__info "PHASE_START phase=validate-config"
+    local cfg="${RALPH_WORK_DIR}/.ralph/config.yaml"
+    if [[ ! -f "$cfg" ]]; then
+        setup__err "${RALPH_TARGET_REPO} is missing .ralph/config.yaml — refusing to continue"
+        return 2
+    fi
+    if ! ralph-validate-config "$cfg" >/dev/null; then
+        setup__err "${cfg} failed schema validation"
+        return 2
+    fi
+    RALPH_CONFIG="$cfg"
+    export RALPH_CONFIG
+    setup__info "PHASE_END phase=validate-config config=${cfg}"
+}
+
+# ---- write setup.env for ralph-orchestrate -----------------------------------
+
+setup__write_env_file() {
+    install -d -m 755 /tmp/ralph
+    cat > /tmp/ralph/setup.env <<EOF
+RALPH_WORK_DIR=${RALPH_WORK_DIR}
+RALPH_DEFAULT_BRANCH=${RALPH_DEFAULT_BRANCH}
+RALPH_CONFIG=${RALPH_CONFIG}
+RALPH_LAUNCH_TAG=${RALPH_LAUNCH_TAG}
+EOF
+    chmod 644 /tmp/ralph/setup.env
+}
+
+# ---- main --------------------------------------------------------------------
+
+setup__main() {
+    local now
+    now=$(date -u +%FT%TZ)
+    setup__info "ralph-harness slice 5 system-setup"
+    setup__info "instance=${INSTANCE_ID} region=${REGION} ts=${now}"
+    setup__info "target=${RALPH_TARGET_REPO:-unset} log_group=${RALPH_LOG_GROUP} log_stream=${LOG_STREAM}"
+
+    setup__start_cwagent
+    setup__install_deps    || return $?
+    setup__fetch_secrets   || return $?
+    setup__clone_target    || return $?
+    setup__safety_guards   || return $?
+    setup__configure_mcps  || return $?
+    setup__validate_config || return $?
+    setup__write_env_file
+}
+
+setup__main 2>&1 | tee -a "$LOG_FILE"

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@unimatrix27/ralph-harness",
+  "version": "1.0.0",
+  "description": "Throwaway-EC2 loop that picks one ready-for-agent GitHub issue, implements it, opens a PR, runs one auto-review pass, then terminates.",
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "bin": {
+    "ralph-bootstrap-aws": "dist/bin/ralph-bootstrap-aws.js",
+    "ralph-fire": "dist/bin/ralph-fire.js",
+    "ralph-gsm": "dist/bin/ralph-gsm.js",
+    "ralph-orchestrate": "dist/bin/ralph-orchestrate.js",
+    "ralph-sync-credential": "dist/bin/ralph-sync-credential.js",
+    "ralph-sync-github-pat": "dist/bin/ralph-sync-github-pat.js",
+    "ralph-tail-logs": "dist/bin/ralph-tail-logs.js",
+    "ralph-validate-config": "dist/bin/ralph-validate-config.js"
+  },
+  "files": [
+    "dist/",
+    "lib/cloud-init/",
+    "prompts/",
+    "README.md",
+    "CONTRIBUTING.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@aws-sdk/client-cloudwatch-logs": "^3.700.0",
+    "@aws-sdk/client-ec2": "^3.700.0",
+    "@aws-sdk/client-iam": "^3.700.0",
+    "@aws-sdk/client-kms": "^3.700.0",
+    "@aws-sdk/client-ssm": "^3.700.0",
+    "@aws-sdk/client-sts": "^3.700.0",
+    "yaml": "^2.8.4",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/unimatrix27/ralph-harness.git"
+  },
+  "license": "MIT"
+}