@stll/oxlint-config 1.0.2 → 1.2.0

package/dist/toolchain-inputs.mjs

@@ -1,5 +1,9 @@
 import path from "node:path";
+import { createHash } from "node:crypto";
 import { subset, valid, validRange } from "semver";
+import { parse as parse$1 } from "smol-toml";
+import { isDeepStrictEqual } from "node:util";
+import { parseDocument } from "yaml";
 import picomatch from "picomatch";
 //#region src/cloud-setup-install.ts
 const packageInstall = String.raw`
@@ -35,7 +39,7 @@ apt_install() (
   policy_state=installed
   printf '%s\n' '#!/bin/sh' 'exit 101' > /usr/sbin/policy-rc.d
   chmod 755 /usr/sbin/policy-rc.d
-  DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends "$@"
+  DEBIAN_FRONTEND=noninteractive apt_network install -y --no-install-recommends "$@"
 )
 
 `;
@@ -159,7 +163,7 @@ const postgresInstall = String.raw`
     if [[ "$PGDG_SOURCE_STATE" == missing ]]; then
       local key key_fingerprint
       key="$(mktemp)"
-      curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 https://www.postgresql.org/media/keys/ACCC4CF8.asc -o "$key"
+      download_file https://www.postgresql.org/media/keys/ACCC4CF8.asc "$key" 45
       key_fingerprint="$(pgdg_key_fingerprint "$key")"
       [[ "$key_fingerprint" == @PGDG_FINGERPRINT@ ]] || fail 'PostgreSQL signing key mismatch'
       install -d -m 755 /usr/share/keyrings
@@ -167,7 +171,7 @@ const postgresInstall = String.raw`
       rm -- "$key"
       printf '%s\n' '@PGDG_SOURCE@' > /etc/apt/sources.list.d/stll-pgdg.list
     fi
-    apt-get update
+    apt_refresh_for postgresql-@POSTGRES@ postgresql-client-@POSTGRES@
     apt_install postgresql-@POSTGRES@ postgresql-client-@POSTGRES@
   fi
   postgres_ready || fail 'PostgreSQL toolchain is incomplete or differs from the policy major'
@@ -182,15 +186,15 @@ const valkeyInstall = String.raw`
       arm64) server_url='@ARM64_SERVER_URL@'; server_sha='@ARM64_SERVER_SHA@'; tools_url='@ARM64_TOOLS_URL@'; tools_sha='@ARM64_TOOLS_SHA@' ;;
       *) fail 'Unsupported Valkey architecture' ;;
     esac
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "$server_url" -o "$scratch/valkey-server.deb"
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "$tools_url" -o "$scratch/valkey-tools.deb"
+    download_file "$server_url" "$scratch/valkey-server.deb" 120
+    download_file "$tools_url" "$scratch/valkey-tools.deb" 120
     (cd "$scratch"; printf '%s  %s\n' "$server_sha" valkey-server.deb "$tools_sha" valkey-tools.deb | sha256sum --strict -c -)
     for package in valkey-server valkey-tools; do
       [[ "$(dpkg-deb -f "$scratch/$package.deb" Package)" == "$package" ]] || fail 'Valkey artifact package mismatch'
       [[ "$(dpkg-deb -f "$scratch/$package.deb" Version)" == '@VALKEY@-1.noble' ]] || fail 'Valkey artifact version mismatch'
       [[ "$(dpkg-deb -f "$scratch/$package.deb" Architecture)" == "$ARCH" ]] || fail 'Valkey artifact architecture mismatch'
     done
-    apt-get update
+    apt_refresh_for "$scratch/valkey-server.deb" "$scratch/valkey-tools.deb"
     apt_install "$scratch/valkey-server.deb" "$scratch/valkey-tools.deb"
     rm -rf -- "$scratch"
   fi
@@ -254,18 +258,267 @@ const renderCloudServiceInstall = ({ services, postgres, valkey, valkeyArtifacts
 	return `${packageInstall}\n${services.includes("postgres") ? postgresSources.replaceAll("@PGDG_FINGERPRINT@", postgresSigningFingerprint) : ""}\n${services.length === 0 ? "prepare_state() { :; }\n" : state}\ninstall_services() {\n${user}${parts.join("")}\n  :\n}\n`;
 };
 //#endregion
+//#region src/cloud-setup-network.ts
+/** Shared deadlines cover retries and package-manager subprocesses. */
+const renderCloudNetwork = () => String.raw`
+network_run() (
+  local host="$1" seconds="$2" status=0
+  shift 2
+  set -o pipefail
+  network_log="$(mktemp)" || return "$?"
+  trap 'rm -f -- "$network_log"' EXIT
+  trap 'exit 129' HUP
+  trap 'exit 130' INT
+  trap 'exit 143' TERM
+  if timeout --signal=TERM --kill-after=5s "$seconds"s "$@" 2>&1 | tee "$network_log"; then
+    return 0
+  else
+    # Scalar Bash array expansion reads PIPESTATUS[0] before assignment resets it.
+    status="$PIPESTATUS"
+  fi
+  [[ "$status" != 0 ]] || fail 'Cannot capture network command output'
+  if [[ "$status" == 124 || "$status" == 137 || "$status" == 28 ]] || grep -Eiq 'timed[[:space:]-]+out|time[[:space:]-]+out|timeout[[:space:]]+(was[[:space:]]+)?(reached|expired)|(connection|operation|socket)[[:space:]-]+timeout' "$network_log"; then
+    fail "download timed out: $host"
+  fi
+  return "$status"
+)
+download_file() {
+  local url="$1" destination="$2" seconds="$3" host
+  host="$(printf '%s\n' "$url" | cut -d/ -f3 | sed 's/.*@//')"
+  [[ "$url" == https://* && -n "$host" ]] || fail 'Downloads require an HTTPS host'
+  network_run "$host" "$seconds" curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 --connect-timeout 20 --max-time "$seconds" --retry 3 --retry-all-errors --retry-max-time "$seconds" "$url" -o "$destination"
+}
+apt_network() {
+  local hosts
+  # --print-uris reads configured indexes without contacting their servers.
+  hosts="$(set -o pipefail; apt-get --print-uris update | awk -F/ '/^\047https?:\/\// { host=$3; sub(/.*@/, "", host); if (!seen[host]++) { printf "%s%s", separator, host; separator="," } }')" || return "$?"
+  [[ -n "$hosts" ]] || hosts='configured APT hosts'
+  network_run "$hosts" 180 apt-get -o Acquire::http::Timeout=20 -o Acquire::https::Timeout=20 -o Acquire::Retries=3 -o APT::Update::Error-Mode=any "$@"
+}
+apt_refresh_for() {
+  # Skip the refresh only when the install downloads nothing: then no package
+  # source is contacted and stale cached indexes cannot point at missing files.
+  local uris
+  if uris="$(DEBIAN_FRONTEND=noninteractive apt-get --print-uris -qq -y --no-install-recommends install "$@" 2>/dev/null)" && [[ -z "$uris" ]]; then
+    return 0
+  fi
+  apt_network update
+}
+`;
+//#endregion
+//#region src/cloud-setup-artifacts.ts
+const wasmBindgen0126 = {
+	version: "0.2.126",
+	amd64: {
+		url: "https://github.com/wasm-bindgen/wasm-bindgen/releases/download/0.2.126/wasm-bindgen-0.2.126-x86_64-unknown-linux-musl.tar.gz",
+		sha256: "064948d58e2d6c0a745216477a639ba696216d6309aaa902939d1b865b1d869d",
+		archive: "tar.gz",
+		binaries: {
+			"wasm-bindgen-test-runner": "wasm-bindgen-0.2.126-x86_64-unknown-linux-musl/wasm-bindgen-test-runner",
+			wasm2es6js: "wasm-bindgen-0.2.126-x86_64-unknown-linux-musl/wasm2es6js",
+			"wasm-bindgen": "wasm-bindgen-0.2.126-x86_64-unknown-linux-musl/wasm-bindgen"
+		}
+	},
+	arm64: {
+		url: "https://github.com/wasm-bindgen/wasm-bindgen/releases/download/0.2.126/wasm-bindgen-0.2.126-aarch64-unknown-linux-musl.tar.gz",
+		sha256: "2245120254a9f6c9a9adf3601f3d52bb31309219e9ceab7696e74e24885c440a",
+		archive: "tar.gz",
+		binaries: {
+			"wasm-bindgen-test-runner": "wasm-bindgen-0.2.126-aarch64-unknown-linux-musl/wasm-bindgen-test-runner",
+			wasm2es6js: "wasm-bindgen-0.2.126-aarch64-unknown-linux-musl/wasm2es6js",
+			"wasm-bindgen": "wasm-bindgen-0.2.126-aarch64-unknown-linux-musl/wasm-bindgen"
+		}
+	}
+};
+/** Pinned upstream Linux artifacts, verified against their published SHA-256 sums. */
+const cloudSetupArtifacts = {
+	"rustup-init": {
+		version: "1.29.1",
+		amd64: {
+			url: "https://static.rust-lang.org/rustup/archive/1.29.1/x86_64-unknown-linux-gnu/rustup-init",
+			sha256: "dda7234360b7f578ca8b0ddcb80145646fa61a67c1720a5abc7051b35c9fcb71",
+			archive: "binary",
+			binaries: { "rustup-init": "rustup-init" }
+		},
+		arm64: {
+			url: "https://static.rust-lang.org/rustup/archive/1.29.1/aarch64-unknown-linux-gnu/rustup-init",
+			sha256: "15f6e4ce9f583b929c996c91562bad6d4454f3281de858b02cdfdef615fac433",
+			archive: "binary",
+			binaries: { "rustup-init": "rustup-init" }
+		}
+	},
+	"cargo-nextest": {
+		version: "0.9.148",
+		amd64: {
+			url: "https://github.com/nextest-rs/nextest/releases/download/cargo-nextest-0.9.148/cargo-nextest-0.9.148-x86_64-unknown-linux-musl.tar.gz",
+			sha256: "bf92cb81450872d960ffa13857a83084d557ec0cdc141663d263bb23ef756f97",
+			archive: "tar.gz",
+			binaries: { "cargo-nextest": "cargo-nextest" }
+		},
+		arm64: {
+			url: "https://github.com/nextest-rs/nextest/releases/download/cargo-nextest-0.9.148/cargo-nextest-0.9.148-aarch64-unknown-linux-musl.tar.gz",
+			sha256: "94676506ceaed01746d78cfe9ed124ee841b2932fd18d9d10f438a347bd9ba5e",
+			archive: "tar.gz",
+			binaries: { "cargo-nextest": "cargo-nextest" }
+		}
+	},
+	"wasm-bindgen-cli": {
+		version: "0.2.129",
+		amd64: {
+			url: "https://github.com/wasm-bindgen/wasm-bindgen/releases/download/0.2.129/wasm-bindgen-0.2.129-x86_64-unknown-linux-musl.tar.gz",
+			sha256: "82d12bb940e2d4e72e0d5605387fc1b8ca179044e012b620f0ce4e7440e8320e",
+			archive: "tar.gz",
+			binaries: {
+				"wasm-bindgen-test-runner": "wasm-bindgen-0.2.129-x86_64-unknown-linux-musl/wasm-bindgen-test-runner",
+				wasm2es6js: "wasm-bindgen-0.2.129-x86_64-unknown-linux-musl/wasm2es6js",
+				"wasm-bindgen": "wasm-bindgen-0.2.129-x86_64-unknown-linux-musl/wasm-bindgen"
+			}
+		},
+		arm64: {
+			url: "https://github.com/wasm-bindgen/wasm-bindgen/releases/download/0.2.129/wasm-bindgen-0.2.129-aarch64-unknown-linux-musl.tar.gz",
+			sha256: "2ed4351c35dd9440308bbb02767d47ea278efe851a52465300f3c94f5b6c2a87",
+			archive: "tar.gz",
+			binaries: {
+				"wasm-bindgen-test-runner": "wasm-bindgen-0.2.129-aarch64-unknown-linux-musl/wasm-bindgen-test-runner",
+				wasm2es6js: "wasm-bindgen-0.2.129-aarch64-unknown-linux-musl/wasm2es6js",
+				"wasm-bindgen": "wasm-bindgen-0.2.129-aarch64-unknown-linux-musl/wasm-bindgen"
+			}
+		}
+	},
+	uv: {
+		version: "0.13.1",
+		amd64: {
+			url: "https://github.com/astral-sh/uv/releases/download/0.13.1/uv-x86_64-unknown-linux-musl.tar.gz",
+			sha256: "6c86040a8f045ab9adc9e3ec4cdafa03fd00e9a988ed2bf28971c7fc2d0debd0",
+			archive: "tar.gz",
+			binaries: {
+				uv: "uv-x86_64-unknown-linux-musl/uv",
+				uvx: "uv-x86_64-unknown-linux-musl/uvx"
+			}
+		},
+		arm64: {
+			url: "https://github.com/astral-sh/uv/releases/download/0.13.1/uv-aarch64-unknown-linux-musl.tar.gz",
+			sha256: "345a8308e4d1835cdfaadf692836fd3137a6d45864773f05ad7bf59442b1ba16",
+			archive: "tar.gz",
+			binaries: {
+				uv: "uv-aarch64-unknown-linux-musl/uv",
+				uvx: "uv-aarch64-unknown-linux-musl/uvx"
+			}
+		}
+	}
+};
+/** Explicit releases whose CLI must match a project's wasm-bindgen crate exactly. */
+const wasmBindgenArtifactReleases = [wasmBindgen0126, cloudSetupArtifacts["wasm-bindgen-cli"]];
+/** Every supported version participates in lookup and catalog validation. */
+const cloudSetupArtifactVersions = {
+	"rustup-init": [cloudSetupArtifacts["rustup-init"]],
+	"cargo-nextest": [cloudSetupArtifacts["cargo-nextest"]],
+	"wasm-bindgen-cli": wasmBindgenArtifactReleases,
+	uv: [cloudSetupArtifacts.uv]
+};
+/** A new version requires an explicit, verified catalog entry; never build from source. */
+const getCloudSetupArtifact = (tool, version) => {
+	const releases = cloudSetupArtifactVersions[tool];
+	const artifact = releases.find((release) => release.version === version);
+	if (artifact === void 0) throw new Error(`Unsupported ${tool} version ${version}; supported versions: ${releases.map((release) => release.version).join(", ")}`);
+	return artifact;
+};
+/** Ubuntu 24.04 packages; apt resolves them from the image's configured sources. */
+const cloudSetupPackages = { time: {
+	version: "1.9",
+	package: "time",
+	binary: "/usr/bin/time",
+	identity: "time (GNU Time) "
+} };
+/** Ubuntu 24.04 ships one release per package; other versions are unsupported. */
+const getCloudSetupPackage = (tool, version) => {
+	const release = cloudSetupPackages[tool];
+	if (release.version !== version) throw new Error(`Unsupported ${tool} version ${version}; supported versions: ${release.version}`);
+	return release;
+};
+//#endregion
 //#region src/cloud-setup-schema.ts
 const cloudServices = ["postgres", "valkey"];
+const cloudArtifactTools = Object.keys(cloudSetupArtifacts).filter((tool) => tool !== "rustup-init" && Object.hasOwn(cloudSetupArtifacts, tool));
+const cloudPackageTools = Object.keys(cloudSetupPackages).filter((tool) => Object.hasOwn(cloudSetupPackages, tool));
+const cloudExtraTools = [...cloudArtifactTools, ...cloudPackageTools];
+const isCloudPackageTool = (tool) => cloudPackageTools.some((candidate) => candidate === tool);
+const object = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+const exactPin = (input) => typeof input === "string" && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(input);
+const exactToolPin = (tool, input) => isCloudPackageTool(tool) ? typeof input === "string" && /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)(?:\.(?:0|[1-9]\d*))?$/.test(input) : exactPin(input);
+const cloudRustComponentBinaries = {
+	clippy: ["cargo-clippy", "clippy-driver"],
+	rustfmt: ["rustfmt", "cargo-fmt"],
+	"rust-src": [],
+	"rust-analyzer": ["rust-analyzer"]
+};
+const parseCloudRustNames = (input, kind) => {
+	const label = `cloud Rust ${kind}`;
+	if (input === void 0) return [];
+	if (!Array.isArray(input)) throw new Error(`${label} must be an array`);
+	const result = input.map((value) => {
+		if (typeof value !== "string" || !/^[a-z][a-z0-9_-]*$/.test(value)) throw new Error(`${label} requires canonical names`);
+		if (kind === "components" && !Object.hasOwn(cloudRustComponentBinaries, value)) throw new Error(`${label} contains an unsupported component: ${value}`);
+		return value;
+	});
+	if (new Set(result).size !== result.length) throw new Error(`${label} contains duplicates`);
+	return result;
+};
+const parseRust = (input) => {
+	if (input === void 0) return void 0;
+	if (!object(input) || Object.keys(input).some((key) => ![
+		"toolchain",
+		"components",
+		"targets"
+	].includes(key))) throw new Error("cloud.rust accepts only toolchain, components and targets");
+	const toolchain = input["toolchain"];
+	if (toolchain !== void 0 && !exactPin(toolchain)) throw new Error("cloud.rust.toolchain must be an exact stable release");
+	return {
+		...toolchain === void 0 ? {} : { toolchain },
+		components: parseCloudRustNames(input["components"], "components"),
+		targets: parseCloudRustNames(input["targets"], "targets")
+	};
+};
+const parseTools = (input) => {
+	if (input === void 0) return void 0;
+	if (!object(input) || Object.keys(input).some((key) => !cloudExtraTools.some((tool) => tool === key))) throw new Error(`cloud.tools accepts only ${cloudExtraTools.join(", ")}`);
+	const result = {};
+	for (const tool of cloudExtraTools) {
+		const pin = input[tool];
+		if (pin === void 0) {
+			if (Object.hasOwn(input, tool)) throw new Error(`cloud.tools.${tool} must be an exact stable release`);
+			continue;
+		}
+		if (!exactToolPin(tool, pin)) throw new Error(`cloud.tools.${tool} must be an exact stable release`);
+		result[tool] = pin;
+	}
+	return result;
+};
 const cloudInstallCommand = "bun install --frozen-lockfile";
+const cloudInstallCommands = [cloudInstallCommand, `${cloudInstallCommand} --ignore-scripts`];
+const cloudInstall = (value) => cloudInstallCommands.some((command) => value === command);
 const cloudService = (value) => cloudServices.some((service) => value === service);
+const parseEnvFile = (input) => {
+	if (!("envFile" in input) || typeof input.envFile !== "string") throw new Error("cloud.envFile must be a canonical repository-relative path");
+	const envFile = input.envFile;
+	if (envFile.startsWith("/") || /^[A-Za-z]:/.test(envFile) || envFile.includes("\\") || /\p{Cc}/u.test(envFile) || envFile.split("/").some((part) => part === "" || part === "." || part === "..")) throw new Error("cloud.envFile must be a canonical repository-relative path");
+	return envFile;
+};
 /** Parse an explicit declaration without assuming services for undeclared repositories. */
 const parseCloudSetup = (input) => {
 	if (input === void 0) return void 0;
 	if (typeof input !== "object" || input === null || Array.isArray(input)) throw new Error("cloud must be an object");
-	for (const key of Object.keys(input)) if (key !== "services" && key !== "install" && key !== "envFile") throw new Error(`unsupported cloud key: ${key}`);
+	for (const key of Object.keys(input)) if (key !== "services" && key !== "install" && key !== "envFile" && key !== "rust" && key !== "tools") throw new Error(`unsupported cloud key: ${key}`);
+	const rust = parseRust("rust" in input ? input.rust : void 0);
+	const tools = parseTools("tools" in input ? input.tools : void 0);
+	const extensions = {
+		...rust === void 0 ? {} : { rust },
+		...tools === void 0 ? {} : { tools }
+	};
 	const selected = "services" in input ? input.services : [];
 	if (!Array.isArray(selected)) throw new Error("cloud.services must be an array when provided");
-	if (!("install" in input) || input.install !== "bun install --frozen-lockfile") throw new Error(`cloud.install must be exactly ${cloudInstallCommand}`);
+	if (!("install" in input) || !cloudInstall(input.install)) throw new Error(`cloud.install must be exactly one of: ${cloudInstallCommands.join(", ")}`);
+	const install = input.install;
 	const seen = /* @__PURE__ */ new Set();
 	const services = Array.from(selected, (service) => {
 		if (!cloudService(service)) throw new Error("cloud.services contains an unsupported service");
@@ -273,20 +526,12 @@ const parseCloudSetup = (input) => {
 		seen.add(service);
 		return service;
 	});
-	if (services.length === 0) {
-		if ("envFile" in input) throw new Error("cloud.envFile is not allowed without services");
-		return {
-			services,
-			install: cloudInstallCommand
-		};
-	}
-	if (!("envFile" in input) || typeof input.envFile !== "string") throw new Error("cloud.envFile must be a canonical repository-relative path");
-	const envFile = input.envFile;
-	if (envFile.startsWith("/") || /^[A-Za-z]:/.test(envFile) || envFile.includes("\\") || /\p{Cc}/u.test(envFile) || envFile.split("/").some((part) => part === "" || part === "." || part === "..")) throw new Error("cloud.envFile must be a canonical repository-relative path");
+	if (services.length === 0 && "envFile" in input) throw new Error("cloud.envFile is not allowed without services");
 	return {
 		services,
-		install: cloudInstallCommand,
-		envFile
+		install,
+		...extensions,
+		...services.length === 0 ? {} : { envFile: parseEnvFile(input) }
 	};
 };
 //#endregion
@@ -353,7 +598,7 @@ service_prune_pid() {
 }
 `;
 const postgresStart = String.raw`
-  local pg_bin='/usr/lib/postgresql/@POSTGRES@/bin' pg_data="$STATE/postgres" pg_password pg_details pg_pid pg_version
+  local pg_bin='/usr/lib/postgresql/@POSTGRES@/bin' pg_data="$STATE/postgres" pg_password pg_details pg_pid pg_version pg_state='already running'
   service_password "$STATE/postgres.password"
   pg_password="$(cat "$STATE/postgres.password")"
   service_directory "$pg_data"
@@ -372,6 +617,7 @@ const postgresStart = String.raw`
   service_prune_pid "$pg_data/postmaster.pid" "$pg_bin/postgres" postgres
   if ! service_run env PGHOST=127.0.0.1 PGHOSTADDR=127.0.0.1 "$pg_bin/pg_ctl" -D "$pg_data" status >/dev/null 2>&1; then
     service_run env PGHOST=127.0.0.1 PGHOSTADDR=127.0.0.1 "$pg_bin/pg_ctl" -D "$pg_data" -l "$pg_data/cloud.log" -o "-h 127.0.0.1 -p 55432 -c unix_socket_directories=" -t 10 -w start >/dev/null || fail "PostgreSQL start failed; port 55432 must be available"
+    pg_state=started
   fi
   pg_details="$(env -u PGSERVICE -u PGSERVICEFILE -u PGOPTIONS PGHOSTADDR=127.0.0.1 PGPASSWORD="$pg_password" PGCONNECT_TIMEOUT=2 "$pg_bin/psql" -X -h 127.0.0.1 -p 55432 -U stll_cloud -d postgres -At -v ON_ERROR_STOP=1 -c "SELECT current_setting('data_directory'), current_setting('listen_addresses'), current_setting('port'), current_setting('server_version_num'), current_setting('unix_socket_directories')")" || fail "PostgreSQL authenticated readiness failed"
   pg_version="$(printf '%s\n' "$pg_details" | cut -d '|' -f4)"
@@ -381,9 +627,10 @@ const postgresStart = String.raw`
   service_process "$pg_pid" "$pg_bin/postgres"
   [[ "$(env -u PGSERVICE -u PGSERVICEFILE -u PGOPTIONS PGHOSTADDR=127.0.0.1 PGPASSWORD="$pg_password" PGCONNECT_TIMEOUT=2 "$pg_bin/psql" -X -h 127.0.0.1 -p 55432 -U stll_cloud -d postgres -At -v ON_ERROR_STOP=1 -c "SELECT count(*) FROM pg_database WHERE datname = 'cloud_test'")" == 1 ]] || env -u PGSERVICE -u PGSERVICEFILE -u PGOPTIONS PGHOSTADDR=127.0.0.1 PGPASSWORD="$pg_password" PGCONNECT_TIMEOUT=2 "$pg_bin/createdb" -h 127.0.0.1 -p 55432 -U stll_cloud cloud_test || fail "PostgreSQL test database creation failed"
   DATABASE_URL="postgresql://stll_cloud:$pg_password@127.0.0.1:55432/cloud_test"
+  printf 'postgres: %s\n' "$pg_state"
 `;
 const valkeyStart = String.raw`
-  local vk_data="$STATE/valkey" vk_password vk_config vk_info vk_pid vk_expected ready=0
+  local vk_data="$STATE/valkey" vk_password vk_config vk_info vk_pid vk_expected ready=0 vk_state='already running'
   service_password "$STATE/valkey.password"
   vk_password="$(cat "$STATE/valkey.password")"
   service_directory "$vk_data"
@@ -403,7 +650,8 @@ const valkeyStart = String.raw`
   [[ "$(cat "$vk_config")" == "$vk_expected" ]] || fail "Valkey configuration differs from managed settings"
   service_prune_pid "$vk_data/valkey.pid" "$(command -v valkey-server)" valkey
   if [[ ! -e "$vk_data/valkey.pid" ]]; then
-    service_run valkey-server "$vk_config" || fail "Valkey start failed; port 56379 must be available"
+    service_run valkey-server "$vk_config" >/dev/null || fail "Valkey start failed; port 56379 must be available"
+    vk_state=started
   fi
   for ((attempt=0; attempt<20; attempt++)); do
     if vk_info="$(VALKEYCLI_AUTH="$vk_password" timeout 0.2 valkey-cli -h 127.0.0.1 -p 56379 --raw INFO server 2>/dev/null)"; then
@@ -419,6 +667,7 @@ const valkeyStart = String.raw`
   [[ "$(VALKEYCLI_AUTH="$vk_password" timeout 2 valkey-cli -h 127.0.0.1 -p 56379 --raw CONFIG GET bind)" == $'bind\n127.0.0.1' ]] || fail "Valkey endpoint must bind only loopback"
   [[ "$(VALKEYCLI_AUTH="$vk_password" timeout 2 valkey-cli -h 127.0.0.1 -p 56379 --raw CONFIG GET dir)" == "$(printf 'dir\n%s' "$vk_data")" ]] || fail "Valkey endpoint has a different data directory"
   REDIS_URL="redis://:$vk_password@127.0.0.1:56379/0"
+  printf 'valkey: %s\n' "$vk_state"
 `;
 /** Render only declared services; installation and environment-file ownership stay with the caller. */
 const renderCloudServiceStart = ({ services, postgres, valkey }) => {
@@ -434,6 +683,300 @@ const renderCloudServiceStart = ({ services, postgres, valkey }) => {
 	return `${common}\nstart_services() {\n  local SERVICE_UID file attempt\n  SERVICE_UID="$(id -u stll-cloud)"\n  [[ -d "$STATE" && ! -L "$STATE" && "$(stat -c '%u' "$STATE")" == 0 ]] || fail "Invalid cloud service state directory"\n${bodies.join("")}\n}\n`;
 };
 //#endregion
+//#region src/cloud-setup-shell.ts
+const cloudShellProfilePath = "/etc/profile.d/stll-cloud.sh";
+const cloudShellProfileSource = `. ${cloudShellProfilePath}`;
+const quote$1 = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const renderCloudShellProfile = ({ nodeVersion, bunVersion, rust }) => {
+	const node = `/opt/stll-cloud/node/${nodeVersion}/bin`;
+	const bun = `/opt/stll-cloud/bun/${bunVersion}`;
+	return `# Generated by stll-cloud-setup; managed cloud shell environment.
+# Remove managed entries before prepending, including repeated shell startup.
+_stll_cloud_remaining="\${PATH-}"
+_stll_cloud_result=''
+_stll_cloud_separator=''
+while :; do
+  case "$_stll_cloud_remaining" in
+    *:*) _stll_cloud_part="\${_stll_cloud_remaining%%:*}"; _stll_cloud_remaining="\${_stll_cloud_remaining#*:}"; _stll_cloud_more=yes ;;
+    *) _stll_cloud_part="$_stll_cloud_remaining"; _stll_cloud_more=no ;;
+  esac
+  case "$_stll_cloud_part" in
+    ${quote$1(node)}|${quote$1(bun)}|/usr/local/bin) ;;
+    *) _stll_cloud_result="$_stll_cloud_result$_stll_cloud_separator$_stll_cloud_part"; _stll_cloud_separator=: ;;
+  esac
+  [ "$_stll_cloud_more" = yes ] || break
+done
+export PATH=${quote$1(`${node}:${bun}:/usr/local/bin`)}"\${_stll_cloud_separator:+:}$_stll_cloud_result"
+unset _stll_cloud_remaining _stll_cloud_result _stll_cloud_separator _stll_cloud_part _stll_cloud_more
+${rust === void 0 ? "" : `export RUSTUP_HOME=/opt/stll-cloud/rustup\nexport CARGO_HOME=/opt/stll-cloud/cargo\nexport RUSTUP_TOOLCHAIN=${quote$1(rust.channel)}\nexport RUSTUP_AUTO_INSTALL=0\n`}`;
+};
+const userStartup = String.raw`
+set -euo pipefail
+for name in .bashrc .profile .bash_profile .bash_login; do
+  file="$HOME/$name"
+  if [[ ! -e "$file" && ! -L "$file" && "$name" != .bashrc && "$name" != .profile ]]; then continue; fi
+  [[ ! -L "$file" ]] || { echo "cloud-setup: shell startup file must not be a symlink: $name" >&2; exit 1; }
+  if [[ -e "$file" ]]; then
+    [[ -f "$file" && "$(stat -c '%h:%u' "$file")" == "1:$(id -u)" ]] || { echo "cloud-setup: shell startup file must be owned and single-link: $name" >&2; exit 1; }
+  fi
+  temporary="$(mktemp "$HOME/.stll-cloud-shell.XXXXXX")"
+  trap 'rm -f -- "$temporary"' EXIT
+  if [[ "$name" == .bashrc ]]; then
+    printf '%s\n' '# stll-cloud: early environment' '@SOURCE@' > "$temporary"
+  fi
+  if [[ -f "$file" ]]; then
+    # Remove only exact managed blocks; preserve unrelated startup lines and permissions.
+    awk '
+      $0 == "# stll-cloud: early environment" || $0 == "# stll-cloud: session environment" {
+        if ((getline following) <= 0 || following != "@SOURCE@") exit 1
+        next
+      }
+      { print }
+    ' "$file" >> "$temporary" || { echo "cloud-setup: managed shell startup block differs: $name" >&2; exit 1; }
+  fi
+  printf '%s\n' '# stll-cloud: session environment' '@SOURCE@' >> "$temporary"
+  if [[ -f "$file" ]] && cmp -s "$temporary" "$file"; then rm -- "$temporary"; continue; fi
+  if [[ -f "$file" ]]; then chmod --reference="$file" "$temporary"; else chmod 644 "$temporary"; fi
+  mv -f -- "$temporary" "$file"
+done
+`;
+const renderCloudShellInstall = (options) => {
+	const profile = renderCloudShellProfile(options);
+	return `install_shell_environment() (
+  # Subshell scope retains temporary for EXIT cleanup after a failed command.
+  [[ ! -L ${quote$1(cloudShellProfilePath)} ]] || fail 'Managed shell profile must not be a symlink'
+  if [[ -e ${quote$1(cloudShellProfilePath)} ]]; then
+    [[ -f ${quote$1(cloudShellProfilePath)} && "$(stat -c '%h:%u' ${quote$1(cloudShellProfilePath)})" == 1:0 ]] || fail 'Managed shell profile must be a root-owned single-link file'
+  fi
+  temporary="$(mktemp)"
+  trap 'rm -f -- "$temporary"' EXIT
+  cat > "$temporary" <<'STLL_CLOUD_PROFILE'
+${profile}STLL_CLOUD_PROFILE
+  if ! cmp -s "$temporary" ${quote$1(cloudShellProfilePath)}; then install -m 644 "$temporary" ${quote$1(cloudShellProfilePath)}; fi
+  runuser -u "$OUTPUT_USER" -- env HOME="$OUTPUT_HOME" bash -c ${quote$1(userStartup.replaceAll("@SOURCE@", cloudShellProfileSource))}
+)
+verify_shell_environment() {
+  [[ -f ${quote$1(cloudShellProfilePath)} && ! -L ${quote$1(cloudShellProfilePath)} && "$(stat -c '%h:%u' ${quote$1(cloudShellProfilePath)})" == 1:0 ]] || fail 'Managed shell environment is unavailable; run install'
+  [[ "$(sha256sum -- ${quote$1(cloudShellProfilePath)} | cut -d ' ' -f1)" == ${quote$1(createHash("sha256").update(profile).digest("hex"))} ]] || fail 'Managed shell environment differs; run install'
+}
+`;
+};
+//#endregion
+//#region src/cloud-setup-toolchains.ts
+const record$2 = (input) => typeof input === "object" && input !== null && !Array.isArray(input);
+/** Resolve the same tracked snapshot for generation and the mandatory drift check. */
+const resolveCloudToolchains = ({ cloud, files, rust, rustExceptions }) => {
+	const source = files["rust-toolchain.toml"];
+	const selector = files["rust-toolchain"];
+	if (source !== void 0 && selector !== void 0) throw new Error("cloud Rust requires one root rust-toolchain.toml or rust-toolchain file");
+	let declared;
+	if (source !== void 0 || selector?.trimStart().startsWith("[")) {
+		const parsed = parse$1(source ?? selector ?? "");
+		if (!record$2(parsed["toolchain"])) throw new Error("cloud Rust requires [toolchain]");
+		declared = parsed["toolchain"];
+		if (Object.keys(declared).some((key) => ![
+			"channel",
+			"components",
+			"targets",
+			"profile"
+		].includes(key))) throw new Error("cloud Rust supports only channel, components, targets and profile");
+		if (declared["profile"] !== void 0 && declared["profile"] !== "minimal") throw new Error("cloud Rust requires profile = minimal; declare required components explicitly");
+	} else if (selector !== void 0) declared = { channel: selector.trim() };
+	const rustEnabled = declared !== void 0 || cloud.rust !== void 0;
+	const channel = declared === void 0 ? cloud.rust?.toolchain ?? rust : declared["channel"];
+	if (rustEnabled) {
+		if (typeof channel !== "string" || !/^\d+\.\d+\.\d+$/.test(channel)) throw new Error("cloud Rust requires an exact stable toolchain");
+		if (channel !== rust && !rustExceptions.some(({ pin }) => pin === channel)) throw new Error(`cloud Rust must use shared Rust ${rust} or a recorded rustExceptions pin`);
+		if (cloud.rust?.toolchain !== void 0 && cloud.rust.toolchain !== channel) throw new Error("cloud.rust.toolchain conflicts with root Rust toolchain");
+	}
+	const components = [.../* @__PURE__ */ new Set([...parseCloudRustNames(declared?.["components"], "components"), ...cloud.rust?.components ?? []])].sort();
+	const targets = [.../* @__PURE__ */ new Set([...parseCloudRustNames(declared?.["targets"], "targets"), ...cloud.rust?.targets ?? []])].sort();
+	const resolveTool = (tool, version) => {
+		if (isCloudPackageTool(tool)) return {
+			type: "package",
+			tool,
+			release: getCloudSetupPackage(tool, version)
+		};
+		if (tool === "cargo-nextest" && !rustEnabled) throw new Error("cloud.tools.cargo-nextest requires a Rust toolchain");
+		if (tool === "wasm-bindgen-cli") {
+			const lock = files["Cargo.lock"];
+			if (lock === void 0) throw new Error("wasm-bindgen-cli requires tracked root Cargo.lock");
+			const packages = parse$1(lock)["package"];
+			if (!Array.isArray(packages)) throw new Error("Cargo.lock requires package entries for wasm-bindgen-cli");
+			const versions = new Set(packages.flatMap((entry) => record$2(entry) && entry["name"] === "wasm-bindgen" ? [entry["version"]] : []));
+			if (versions.size !== 1 || !versions.has(version)) throw new Error(`cloud.tools.wasm-bindgen-cli ${version} must equal the unique wasm-bindgen crate version in Cargo.lock (found ${[...versions].join(", ") || "none"})`);
+		}
+		return {
+			type: "artifact",
+			tool,
+			release: getCloudSetupArtifact(tool, version)
+		};
+	};
+	const tools = cloudExtraTools.flatMap((tool) => {
+		const version = cloud.tools?.[tool];
+		return version === void 0 ? [] : [resolveTool(tool, version)];
+	});
+	return {
+		rust: rustEnabled && typeof channel === "string" ? {
+			channel,
+			components,
+			targets,
+			installer: cloudSetupArtifacts["rustup-init"]
+		} : void 0,
+		tools
+	};
+};
+//#endregion
+//#region src/cloud-setup-tools-install.ts
+const quote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
+const artifactSelection = (release) => `case "$ARCH" in
+${["amd64", "arm64"].map((arch) => `  ${arch}) artifact_url=${quote(release[arch].url)}; artifact_sha=${quote(release[arch].sha256)} ;;`).join("\n")}
+esac`;
+const helpers = String.raw`
+fetch_verified() {
+  download_file "$1" "$3" 120
+  printf '%s  %s\n' "$2" "$3" | sha256sum --strict -c - >/dev/null
+}
+`;
+const rustInstall = (rust) => {
+	const args = [...rust.components.flatMap((name) => ["--component", name]), ...rust.targets.flatMap((name) => ["--target", name])].map(quote).join(" ");
+	return String.raw`
+export RUSTUP_HOME=/opt/stll-cloud/rustup
+export CARGO_HOME=/opt/stll-cloud/cargo
+export RUSTUP_TOOLCHAIN='@RUST@'
+export RUSTUP_AUTO_INSTALL=0
+rust_run() {
+  local mode="$1"
+  shift
+  set -- runuser -u "$OUTPUT_USER" -- env HOME="$OUTPUT_HOME" RUSTUP_HOME="$RUSTUP_HOME" CARGO_HOME="$CARGO_HOME" RUSTUP_AUTO_INSTALL=0 RUSTUP_TOOLCHAIN=@RUST@ RUSTUP_DIST_SERVER=https://static.rust-lang.org RUSTUP_UPDATE_ROOT=https://static.rust-lang.org/rustup PATH="$PATH" "$@"
+  case "$mode" in
+    local) "$@" ;;
+    network) network_run static.rust-lang.org 180 "$@" ;;
+    *) fail 'Invalid Rust execution mode' ;;
+  esac
+}
+rust_ready() {
+  local directory
+  for directory in "$RUSTUP_HOME" "$CARGO_HOME"; do
+    [[ -d "$directory" && ! -L "$directory" && "$(stat -c '%u' "$directory")" == "$OUTPUT_UID" ]] || return 1
+  done
+  [[ -x "$CARGO_HOME/bin/rustup" ]] || return 1
+  [[ "$(rust_run local "$CARGO_HOME/bin/rustup" --version 2>/dev/null)" == 'rustup @RUSTUP@ '* ]] || return 1
+  [[ "$(rust_run local "$CARGO_HOME/bin/rustc" +@RUST@ --version)" == 'rustc @RUST@ '* ]] || return 1
+  local host
+  host="$(rust_run local "$CARGO_HOME/bin/rustc" +@RUST@ -vV | awk '$1 == "host:" { print $2 }')" || return 1
+  @VERIFY_COMPONENTS@
+  @VERIFY_TARGETS@
+  return 0
+}
+verify_rust() { rust_ready || fail 'Pinned Rust, components or targets are unavailable; run install'; }
+install_rust() (
+  if ! command -v cc >/dev/null || ! command -v ld >/dev/null || [[ ! -f /usr/include/stdlib.h ]]; then
+    apt_refresh_for build-essential
+    apt_install build-essential
+  fi
+  local artifact_url artifact_sha
+  # Subshell scope retains scratch for EXIT cleanup after a failed command.
+  scratch="$(mktemp -d)"
+  trap 'rm -rf -- "$scratch"' EXIT
+  for directory in "$RUSTUP_HOME" "$CARGO_HOME"; do
+    [[ ! -L "$directory" ]] || fail 'Rust home must not be a symlink'
+    if [[ -e "$directory" ]]; then
+      [[ -d "$directory" && "$(stat -c '%u' "$directory")" == "$OUTPUT_UID" ]] || fail 'Rust home ownership differs from the invoking user'
+    else
+      install -d -m 755 -o "$OUTPUT_UID" -g "$OUTPUT_GID" "$directory"
+    fi
+  done
+  if [[ ! -x "$CARGO_HOME/bin/rustup" ]] || [[ "$(rust_run local "$CARGO_HOME/bin/rustup" --version 2>/dev/null)" != 'rustup @RUSTUP@ '* ]]; then
+    @RUSTUP_ARTIFACT@
+    fetch_verified "$artifact_url" "$artifact_sha" "$scratch/rustup-init"
+    chmod 755 "$scratch" "$scratch/rustup-init"
+    rust_run network "$scratch/rustup-init" -y --no-modify-path --default-toolchain none --profile minimal
+  fi
+  rust_run local "$CARGO_HOME/bin/rustup" set auto-self-update disable
+  if ! rust_ready; then
+    rust_run network "$CARGO_HOME/bin/rustup" toolchain install @RUST@ --profile minimal --no-self-update @RUST_ARGS@
+  fi
+  rust_run local "$CARGO_HOME/bin/rustup" default @RUST@
+  verify_rust
+  for tool in rustup cargo rustc rustdoc @RUST_PROXIES@; do
+    # Launchers persist the system homes in fresh shells without profile sourcing.
+    printf '%s\n' '#!/bin/sh' 'export RUSTUP_HOME=/opt/stll-cloud/rustup' 'export CARGO_HOME=/opt/stll-cloud/cargo' 'export RUSTUP_AUTO_INSTALL=0' 'export RUSTUP_TOOLCHAIN=@RUST@' "exec /opt/stll-cloud/cargo/bin/$tool \"\$@\"" > "$scratch/$tool"
+    if ! cmp -s "$scratch/$tool" "/usr/local/bin/$tool"; then
+      install -m 755 "$scratch/$tool" "/usr/local/bin/$tool"
+    fi
+  done
+)
+`.replaceAll("@RUSTUP@", rust.installer.version).replaceAll("@RUST@", rust.channel).replace("@RUSTUP_ARTIFACT@", artifactSelection(rust.installer)).replace("@RUST_ARGS@", args).replace("@RUST_PROXIES@", Object.entries(cloudRustComponentBinaries).flatMap(([component, binaries]) => rust.components.includes(component) ? Array.from(binaries) : []).join(" ")).replace("@VERIFY_COMPONENTS@", rust.components.map((name) => `rust_run local "$CARGO_HOME/bin/rustup" component list --toolchain ${quote(rust.channel)} --installed | awk -v name=${quote(name)} -v host="$host" '$1 == name || $1 == name "-" host { found=1 } END { exit !found }' || return 1`).join("\n  ")).replace("@VERIFY_TARGETS@", rust.targets.map((name) => `rust_run local "$CARGO_HOME/bin/rustup" target list --toolchain ${quote(rust.channel)} --installed | awk -v name=${quote(name)} '$1 == name { found=1 } END { exit !found }' || return 1`).join("\n  "));
+};
+const packageToolInstall = ({ tool, release }) => {
+	const name = tool.replaceAll("-", "_");
+	return {
+		name,
+		text: `verify_${name}() {
+  [[ -x ${quote(release.binary)} && "$(${quote(release.binary)} --version 2>/dev/null)" == ${quote(release.identity)}* ]] || return 1
+  [[ "$(dpkg-query -W -f='\${Version}' ${quote(release.package)} 2>/dev/null)" == ${quote(`${release.version}-`)}* ]]
+}
+install_${name}() {
+  if ! verify_${name}; then
+    apt_network update
+    apt_install ${quote(release.package)}
+    verify_${name} || fail ${quote(`Installed ${tool} version differs from its pin`)}
+  fi
+}
+`
+	};
+};
+const artifactToolInstall = ({ tool, release }) => {
+	const directory = `/opt/stll-cloud/tools/${tool}/${release.version}`;
+	const command = tool === "wasm-bindgen-cli" ? "wasm-bindgen" : tool;
+	const marker = `${tool === "cargo-nextest" ? "cargo-nextest" : command} ${release.version}`;
+	return {
+		name: tool.replaceAll("-", "_"),
+		text: `verify_${tool.replaceAll("-", "_")}() {
+  ${Object.keys(release.amd64.binaries).map((binary) => `[[ -x ${quote(`${directory}/${binary}`)} ]] || return 1`).join("\n  ")}
+  [[ "$( ${quote(`${directory}/${command}`)} --version)" == ${quote(marker)} || "$( ${quote(`${directory}/${command}`)} --version)" == ${quote(`${marker} `)}* ]]
+}
+install_${tool.replaceAll("-", "_")}() (
+  local artifact_url artifact_sha
+  # Subshell scope retains scratch for EXIT cleanup after a failed command.
+  if ! verify_${tool.replaceAll("-", "_")}; then
+    scratch="$(mktemp -d)"
+    trap 'rm -rf -- "$scratch"' EXIT
+    ${artifactSelection(release)}
+    fetch_verified "$artifact_url" "$artifact_sha" "$scratch/archive.tar.gz"
+    tar -xzf "$scratch/archive.tar.gz" -C "$scratch"
+    install -d -m 755 ${quote(directory)}
+    case "$ARCH" in
+${["amd64", "arm64"].map((arch) => `      ${arch})\n${Object.entries(release[arch].binaries).map(([binary, path]) => `        install -m 755 "$scratch/${path}" ${quote(`${directory}/${binary}`)}`).join("\n")}\n        ;;`).join("\n")}
+    esac
+    verify_${tool.replaceAll("-", "_")} || fail ${quote(`Installed ${tool} version differs from its pin`)}
+  fi
+${Object.keys(release.amd64.binaries).map((binary) => `  ln -sfnT -- ${quote(`${directory}/${binary}`)} ${quote(`/usr/local/bin/${binary}`)}`).join("\n")}
+)
+`
+	};
+};
+const renderCloudToolInstall = ({ rust, tools }) => {
+	const installs = tools.map((entry) => {
+		switch (entry.type) {
+			case "package": return packageToolInstall(entry);
+			case "artifact": return artifactToolInstall(entry);
+			default: throw new Error(`Unsupported cloud tool: ${String(entry)}`);
+		}
+	});
+	return `${helpers}${rust === void 0 ? "" : rustInstall(rust)}\n${installs.map(({ text }) => text).join("\n")}
+install_tools() {
+  ${rust === void 0 ? ":" : "install_rust"}
+  ${installs.map(({ name }) => `install_${name}`).join("\n  ")}
+}
+verify_tools() {
+  ${rust === void 0 ? ":" : "verify_rust"}
+  ${installs.map(({ name }) => `verify_${name} || fail 'Pinned ${name} is unavailable; run install'`).join("\n  ")}
+}
+`;
+};
+//#endregion
 //#region src/toolchain-node.ts
 const numericComponent = "(?:0|[1-9]\\d*)";
 const policyPattern = new RegExp(`^${numericComponent}\\.x$`);
@@ -471,6 +1014,14 @@ usage() { echo 'Usage: cloud-setup.sh install|start' >&2; exit 2; }
 case "$1" in install|start) MODE="$1" ;; *) usage ;; esac
 fail() { echo "cloud-setup: $*" >&2; exit 1; }
 trap 'echo "cloud-setup: command failed at line $LINENO" >&2' ERR
+# Each phase logs its start and duration so a stalled phase is visible in the task log.
+step() {
+  local name="$1" started="$SECONDS"
+  shift
+  echo "cloud-setup: $name started" >&2
+  "$@"
+  echo "cloud-setup: $name done in $((SECONDS - started))s" >&2
+}
 [[ -f /etc/os-release ]] || fail 'Ubuntu 24.04 is required'
 . /etc/os-release
 [[ "$ID" == ubuntu && "$VERSION_ID" == 24.04 && "$VERSION_CODENAME" == noble ]] || fail 'Only Ubuntu 24.04 (noble) is supported'
@@ -506,22 +1057,24 @@ case "$(uname -m)" in
   *) fail 'Only amd64 and arm64 are supported' ;;
 esac
 
+@NETWORK@
+
 runtime_ready() {
   [[ -x "$NODE_DIR/bin/node" && "$($NODE_DIR/bin/node --version)" == "v$NODE_VERSION" ]] || fail 'Pinned Node is unavailable; run install'
   [[ -x "$BUN_DIR/bun" && "$($BUN_DIR/bun --version)" == "$BUN_VERSION" ]] || fail 'Pinned Bun is unavailable; run install'
 }
 install_runtimes() {
-  if ! command -v curl >/dev/null || ! command -v unzip >/dev/null || ! command -v xz >/dev/null || ! command -v openssl >/dev/null || ! command -v gpg >/dev/null; then
-    apt-get update
-    DEBIAN_FRONTEND=noninteractive apt_install ca-certificates curl unzip xz-utils openssl gnupg util-linux
+  if ! command -v curl >/dev/null || ! command -v unzip >/dev/null || ! command -v xz >/dev/null || ! command -v openssl >/dev/null || ! command -v gpg >/dev/null || ! ldconfig -p | awk '$1 == "libatomic.so.1" { found=1 } END { exit !found }'; then
+    apt_refresh_for ca-certificates curl unzip xz-utils openssl gnupg util-linux libatomic1
+    DEBIAN_FRONTEND=noninteractive apt_install ca-certificates curl unzip xz-utils openssl gnupg util-linux libatomic1
   fi
   local scratch node_archive bun_archive bun_folder
   scratch="$(mktemp -d)"
   trap 'rm -rf -- "$scratch"' RETURN
   if [[ ! -x "$NODE_DIR/bin/node" ]] || [[ "$($NODE_DIR/bin/node --version)" != "v$NODE_VERSION" ]]; then
     node_archive="node-v$NODE_VERSION-linux-$NODE_ARCH.tar.xz"
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "https://nodejs.org/dist/v$NODE_VERSION/$node_archive" -o "$scratch/$node_archive"
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "https://nodejs.org/dist/v$NODE_VERSION/SHASUMS256.txt" -o "$scratch/node-sums"
+    download_file "https://nodejs.org/dist/v$NODE_VERSION/$node_archive" "$scratch/$node_archive" 120
+    download_file "https://nodejs.org/dist/v$NODE_VERSION/SHASUMS256.txt" "$scratch/node-sums" 45
     (cd "$scratch"; awk -v name="$node_archive" '$2 == name { print; count++ } END { if (count != 1) exit 1 }' node-sums | sha256sum --strict -c -)
     install -d -m 755 "$NODE_DIR"
     tar -xJf "$scratch/$node_archive" --strip-components=1 -C "$NODE_DIR"
@@ -529,8 +1082,8 @@ install_runtimes() {
   if [[ ! -x "$BUN_DIR/bun" ]] || [[ "$($BUN_DIR/bun --version)" != "$BUN_VERSION" ]]; then
     bun_folder="bun-linux-$BUN_ARCH"
     bun_archive="$bun_folder.zip"
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/$bun_archive" -o "$scratch/$bun_archive"
-    curl --fail --silent --show-error --location --proto '=https' --proto-redir '=https' --tlsv1.2 "https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/SHASUMS256.txt" -o "$scratch/bun-sums"
+    download_file "https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/$bun_archive" "$scratch/$bun_archive" 120
+    download_file "https://github.com/oven-sh/bun/releases/download/bun-v$BUN_VERSION/SHASUMS256.txt" "$scratch/bun-sums" 45
     (cd "$scratch"; awk -v name="$bun_archive" '$2 == name || $2 == "*" name { print $1 "  " name; count++ } END { if (count != 1) exit 1 }' bun-sums | sha256sum --strict -c -)
     unzip -q "$scratch/$bun_archive" -d "$scratch/bun"
     install -d -m 755 "$BUN_DIR"
@@ -546,7 +1099,7 @@ install_runtimes() {
 }
 
 dependency_install() {
-  local directory
+  local directory download_hosts
   for directory in /var/cache/stll-cloud /var/cache/stll-cloud/bun; do
     [[ ! -L "$directory" ]] || fail 'Dependency cache parent must not be a symlink'
     if [[ -e "$directory" ]]; then
@@ -559,24 +1112,52 @@ dependency_install() {
     [[ -d "$BUN_CACHE" && "$(stat -c '%u' "$BUN_CACHE")" == "$OUTPUT_UID" ]] || fail 'Dependency cache ownership differs from the invoking user'
   fi
   install -d -m 700 -o "$OUTPUT_UID" -g "$OUTPUT_GID" "$BUN_CACHE"
-  runuser -u "$OUTPUT_USER" -- env HOME="$OUTPUT_HOME" BUN_INSTALL_CACHE_DIR="$BUN_CACHE" PATH="$PATH" "$BUN_DIR/bun" install --frozen-lockfile
+  # Report hostnames only: lockfile/config URLs may contain credentials.
+  # These are known install hosts; lifecycle scripts can contact other hosts.
+  download_hosts="$(HOME="$OUTPUT_HOME" "$NODE_DIR/bin/node" -e '
+const fs = require("node:fs");
+const path = require("node:path");
+const hosts = new Set(["registry.npmjs.org"]);
+const inputs = [process.env.BUN_CONFIG_REGISTRY ?? "", process.env.NPM_CONFIG_REGISTRY ?? "", process.env.npm_config_registry ?? ""];
+for (const file of ["bun.lock", ".npmrc", "bunfig.toml", path.join(process.env.HOME, ".npmrc"), path.join(process.env.HOME, ".bunfig.toml"), path.join(process.env.XDG_CONFIG_HOME ?? process.env.HOME, ".bunfig.toml")]) {
+  if (fs.existsSync(file)) inputs.push(fs.readFileSync(file, "utf8"));
+}
+for (const input of inputs) {
+  for (const match of input.matchAll(/(?:git\+)?https?:\/\/[^\s"\x27<>\\]+/g)) {
+    try { hosts.add(new URL(match[0].replace(/^git\+/, "")).hostname); } catch {}
+  }
+  if (/github:/.test(input)) { hosts.add("github.com"); hosts.add("codeload.github.com"); }
+}
+process.stdout.write([...hosts].sort().join(","));
+')"
+  # Bun 1.4.3 socket inactivity timeout, in seconds; the outer bound includes scripts.
+  network_run "$download_hosts" 240 runuser -u "$OUTPUT_USER" -- env HOME="$OUTPUT_HOME" BUN_INSTALL_CACHE_DIR="$BUN_CACHE" PATH="$PATH" BUN_CONFIG_HTTP_IDLE_TIMEOUT=20 "$BUN_DIR/bun" @INSTALL_ARGS@
 }
 
 @SERVICE_INSTALL@
 @SERVICE_START@
 
+@TOOL_INSTALL@
+
+@INPUT_VALIDATION@
+
 @ENV_FUNCTIONS@
 
 if [[ "$MODE" == install ]]; then
-  install_runtimes
-  install_services
-  dependency_install
+  step runtimes install_runtimes
+  step services install_services
+  step tools install_tools
+  step shell install_shell_environment
+  step dependencies dependency_install
   exit 0
 fi
-runtime_ready
+step runtime-check runtime_ready
+step tool-check verify_tools
+step shell install_shell_environment
+step shell-check verify_shell_environment
 @ENV_VALIDATE@
-prepare_state
-start_services
+step state prepare_state
+step service-start start_services
 @ENV_WRITE@
 `;
 const environmentFunctions = String.raw`
@@ -608,13 +1189,36 @@ write_environment() {
 }
 `;
 const shellQuote = (value) => `'${value.replaceAll("'", "'\\''")}'`;
-const generateCloudSetup = ({ policy, cloud, nodeVersion }) => {
+const generateCloudSetup = ({ policy, cloud, nodeVersion, files = {}, rustExceptions = [] }) => {
 	const selected = parseCloudSetup(cloud);
 	if (selected === void 0) throw new Error("cloud declaration is required");
 	const exactNode = nodeVersion.trim();
 	if (valid(exactNode) !== exactNode || !nodeSelectorMatches(exactNode, policy.node)) throw new Error("cloud requires a tracked exact .node-version within the shared Node series");
+	const toolchains = resolveCloudToolchains({
+		cloud: selected,
+		files,
+		rust: policy.rust,
+		rustExceptions
+	});
 	const services = cloudServices.filter((service) => selected.services.includes(service));
 	const replacements = /* @__PURE__ */ new Map([
+		["@INSTALL_ARGS@", selected.install.replace(/^bun /, "")],
+		["@NETWORK@", renderCloudNetwork()],
+		["@TOOL_INSTALL@", renderCloudToolInstall(toolchains) + renderCloudShellInstall({
+			nodeVersion: exactNode,
+			bunVersion: policy.bun,
+			rust: toolchains.rust
+		})],
+		["@INPUT_VALIDATION@", [
+			"rust-toolchain.toml",
+			"rust-toolchain",
+			...selected.tools?.["wasm-bindgen-cli"] === void 0 ? [] : ["Cargo.lock"]
+		].flatMap((file) => {
+			const content = files[file];
+			if (content === void 0) return [`[[ ! -e ${shellQuote(file)} && ! -L ${shellQuote(file)} ]] || fail ${shellQuote(`${file} appeared; regenerate cloud-setup.sh`)}`];
+			const hash = createHash("sha256").update(content).digest("hex");
+			return [`[[ -f ${shellQuote(file)} && ! -L ${shellQuote(file)} ]] && [[ "$(sha256sum -- ${shellQuote(file)} | cut -d ' ' -f1)" == ${shellQuote(hash)} ]] || fail ${shellQuote(`${file} changed; regenerate cloud-setup.sh`)}`];
+		}).join("\n")],
 		["@BUN@", policy.bun],
 		["@NODE@", exactNode],
 		["@ENV_ASSIGNMENTS@", selected.envFile === void 0 ? "" : `ENV_FILE=${shellQuote(selected.envFile)}\nENV_MARKER=${shellQuote(cloudEnvironmentMarker)}`],
@@ -640,6 +1244,129 @@ const generateCloudSetup = ({ policy, cloud, nodeVersion }) => {
 	});
 };
 //#endregion
+//#region src/cloud-setup-claude.ts
+const cloudClaudeSettingsPath = ".claude/settings.json";
+const sessionStartHook = (script) => ({
+	matcher: "",
+	hooks: [{
+		type: "command",
+		command: `if [ "\${CLAUDE_CODE_REMOTE:-}" = "true" ]; then
+  ${script} start || exit "$?"
+  if [ -n "\${CLAUDE_ENV_FILE:-}" ]; then
+    if [ ! -f ${cloudShellProfilePath} ]; then
+      printf '%s\\n' 'cloud-setup: cloud shell profile is unavailable; run install' >&2
+      exit 1
+    fi
+    printf '\\n' >> "$CLAUDE_ENV_FILE" || exit "$?"
+    cat ${cloudShellProfilePath} >> "$CLAUDE_ENV_FILE"
+  fi
+fi`
+	}]
+});
+const cloudSessionStartHook = sessionStartHook(`bash "$CLAUDE_PROJECT_DIR/${cloudSetupPath}"`);
+const previousCloudSessionStartHooks = [sessionStartHook(`bash ${cloudSetupPath}`)];
+const cloudAttribution = {
+	commit: "",
+	pr: ""
+};
+const record$1 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const array = (value) => Array.isArray(value);
+const parseSettings = (text) => {
+	try {
+		return JSON.parse(text, (_key, value) => {
+			if (typeof value === "number" && (!Number.isFinite(value) || Number.isInteger(value) && !Number.isSafeInteger(value))) throw new Error("settings contains a number that cannot be safely preserved");
+			return value;
+		});
+	} catch (error) {
+		if (error instanceof SyntaxError) throw new Error("settings must contain valid JSON");
+		throw error;
+	}
+};
+const readSettings = (text) => {
+	const settings = text === void 0 ? {} : parseSettings(text);
+	if (text !== void 0 && parseDocument(text, { uniqueKeys: true }).errors.length > 0) throw new Error("settings contains duplicate or ambiguous JSON keys");
+	if (!record$1(settings)) throw new Error("settings must be a JSON object");
+	if (settings["disableAllHooks"] === true) throw new Error("disableAllHooks prevents SessionStart from running");
+	const hooks = settings["hooks"] === void 0 ? {} : settings["hooks"];
+	if (!record$1(hooks)) throw new Error("hooks must be a JSON object");
+	const sessionStart = hooks["SessionStart"] === void 0 ? [] : hooks["SessionStart"];
+	if (!array(sessionStart) || sessionStart.some((entry) => !record$1(entry) || !array(entry["hooks"]))) throw new Error("hooks.SessionStart must be an array of hook groups");
+	return {
+		settings,
+		hooks,
+		sessionStart
+	};
+};
+const cloudHookGroups = (sessionStart) => sessionStart.filter((entry) => record$1(entry) && array(entry["hooks"]) && entry["hooks"].some((hook) => record$1(hook) && typeof hook["command"] === "string" && hook["command"].includes(".agents/cloud-setup.sh")));
+const cloudSessionStartFix = `preserve unrelated settings in ${cloudClaudeSettingsPath}, repair its JSON/hooks structure and set disableAllHooks to false if needed, and ensure hooks.SessionStart contains exactly this cloud setup entry (replace conflicting cloud setup entries):\n` + JSON.stringify(cloudSessionStartHook, null, 2);
+const cloudAttributionFix = `preserve unrelated settings in ${cloudClaudeSettingsPath} and set its top-level attribution to exactly:\n` + JSON.stringify({ attribution: cloudAttribution }, null, 2);
+const sessionStartState = (sessionStart) => {
+	const groups = cloudHookGroups(sessionStart);
+	const group = groups.at(0);
+	if (group === void 0) return { type: "missing" };
+	if (groups.length === 1 && isDeepStrictEqual(group, cloudSessionStartHook)) return { type: "current" };
+	if (groups.length === 1 && previousCloudSessionStartHooks.some((hook) => isDeepStrictEqual(group, hook))) return {
+		type: "previous",
+		group
+	};
+	return { type: "conflict" };
+};
+const attributionState = (settings) => {
+	const attribution = settings["attribution"];
+	if (attribution === void 0) return "missing";
+	return isDeepStrictEqual(attribution, cloudAttribution) ? "current" : "conflict";
+};
+const mergeError = (reason, fix) => /* @__PURE__ */ new Error(`cannot safely merge ${cloudClaudeSettingsPath}: ${reason}; ${fix}`);
+const readMergeableSettings = (text) => {
+	try {
+		return readSettings(text);
+	} catch (error) {
+		throw mergeError(error instanceof Error ? error.message : String(error), cloudSessionStartFix);
+	}
+};
+/** Add the cloud hook and attribution; never overwrite conflicting values. */
+const mergeCloudClaudeSettings = (text) => {
+	const { settings, hooks, sessionStart } = readMergeableSettings(text);
+	const hook = sessionStartState(sessionStart);
+	if (hook.type === "conflict") throw mergeError("existing cloud setup SessionStart hook differs", cloudSessionStartFix);
+	const attribution = attributionState(settings);
+	if (attribution === "conflict") throw mergeError("existing attribution differs", cloudAttributionFix);
+	if (hook.type === "current" && attribution === "current" && text !== void 0) return text;
+	const mergedSessionStart = (() => {
+		switch (hook.type) {
+			case "current": return sessionStart;
+			case "missing": return [...sessionStart, cloudSessionStartHook];
+			case "previous": return sessionStart.map((entry) => entry === hook.group ? cloudSessionStartHook : entry);
+			default: throw new Error(`Unsupported hook state: ${String(hook)}`);
+		}
+	})();
+	return `${JSON.stringify({
+		...settings,
+		attribution: cloudAttribution,
+		hooks: {
+			...hooks,
+			SessionStart: mergedSessionStart
+		}
+	}, null, 2)}\n`;
+};
+/** Settings formatting and unrelated hooks do not affect the generated contract. */
+const hasCloudSessionStartHook = (text) => {
+	if (text === void 0) return false;
+	try {
+		return sessionStartState(readSettings(text).sessionStart).type === "current";
+	} catch {
+		return false;
+	}
+};
+const hasCloudAttribution = (text) => {
+	if (text === void 0) return false;
+	try {
+		return attributionState(readSettings(text).settings) === "current";
+	} catch {
+		return false;
+	}
+};
+//#endregion
 //#region src/toolchain-workspaces.ts
 /** Match manifest directories with the same positive and negative workspace patterns. */
 const workspaceContains = ({ directory, file, patterns, rootMembership }) => {
@@ -806,13 +1533,13 @@ const isDockerDefinitionPath = (file) => {
 const isShellScript = (file, text = "") => !excludedInputPath(file) && (/\.(?:sh|bash|zsh)$/.test(file) || /^#![ \t]*(?:\/(?:[^ \t\r\n]+\/)*(?:bash|dash|ksh|zsh|sh)|\/usr\/bin\/env[ \t]+(?:-S[ \t]+)?(?:bash|dash|ksh|zsh|sh))(?=[ \t\r\n]|$)/.test(text));
 /** Lockfiles establish ecosystem presence without reading their dependency graphs. */
 const toolchainInputKind = (file, text = "") => {
-	if (file === ".agents/cloud-setup.sh") return "config";
+	if (file === ".agents/cloud-setup.sh" || file === ".claude/settings.json" || file === "Cargo.lock") return "config";
 	if (githubAutomationFileKind(file) !== void 0) return "config";
 	if (excludedInputPath(file)) return void 0;
 	if (pythonDependencyManifestKind(file) === "pipfile-lock" || javascriptDependencyLockfiles.some((name) => file.split("/").at(-1) === name) || /(?:^|\/)uv\.lock$/.test(file)) return "presence";
 	if (githubAutomationFileKind(file) !== void 0 || isShellScript(file, text) || /(?:^|\/)ci-service-images\.json$/.test(file) || isMiseConfigPath(file) || isPythonDependencyManifest(file) || isDockerDefinitionPath(file) || isComposeDefinitionPath(file) || isKubernetesDefinitionPath(file) || /(?:^|\/)(?:package\.json|consumer-compat\.json|pnpm-workspace\.yaml|stll-toolchain\.json|\.bun-version|\.node-version|\.nvmrc|\.python-version|rust-toolchain(?:\.toml)?|\.tool-versions|\.?mise\.toml|uv\.toml|\.uv\.toml|\.github\/dependabot\.ya?ml|Cargo\.toml)$/.test(file)) return "config";
 };
 //#endregion
-export { nodeSelectorMatches as _, isPythonDependencyManifest as a, pythonDependencyManifestKind as c, isComposeDefinitionPath as d, isKubernetesDefinitionPath as f, nodePolicyValid as g, generateCloudSetup as h, isMiseConfigPath as i, toolchainInputKind as l, cloudSetupPath as m, isDependabotGithubActionsPath as n, isShellScript as o, workspaceContains as p, isDockerDefinitionPath as r, javascriptDependencyLockfiles as s, githubAutomationFileKind as t, containerDocumentImages as u, nodeSupportRangeMatches as v, parseCloudSetup as y };
+export { nodeSelectorMatches as C, nodePolicyValid as S, parseCloudSetup as T, hasCloudAttribution as _, isPythonDependencyManifest as a, cloudSetupPath as b, pythonDependencyManifestKind as c, isComposeDefinitionPath as d, isKubernetesDefinitionPath as f, cloudSessionStartFix as g, cloudClaudeSettingsPath as h, isMiseConfigPath as i, toolchainInputKind as l, cloudAttributionFix as m, isDependabotGithubActionsPath as n, isShellScript as o, workspaceContains as p, isDockerDefinitionPath as r, javascriptDependencyLockfiles as s, githubAutomationFileKind as t, containerDocumentImages as u, hasCloudSessionStartHook as v, nodeSupportRangeMatches as w, generateCloudSetup as x, mergeCloudClaudeSettings as y };
 
 //# sourceMappingURL=toolchain-inputs.mjs.map