cozyclay 1.1.0 → 1.3.0

package/tools/ardy/runners/remote.mjs

@@ -0,0 +1,252 @@
+/**
+ * Remote (ssh) runner for the ARDY bridge.
+ *
+ * This is the original box-driven backend extracted verbatim from bridge.mjs:
+ * health and bases probes go over one ssh round trip each, reference dumps
+ * scp a python script to the box's /tmp, and generation shells out to the
+ * run-*-on-box.sh wrappers, which push inputs, run the generator remotely and
+ * pull the npz back.
+ *
+ * The runner interface (shared with runners/local.mjs) is deliberately small:
+ *
+ *   describe()                     one-line startup log
+ *   probeHealth()                  -> { ok:true, host, encoder, device } | throws
+ *   listBases()                    -> raw entries [{id, path, frames}] | throws
+ *   singleCommand(request)         -> { command, args, env, doneRe }
+ *   sequenceCommand(request)       -> { command, args, env, doneRe }
+ *   editCommand(request)           -> { command, args, env, doneRe }
+ *
+ * The bridge owns validation, caching, streaming and the motion allowlist;
+ * a runner only knows how to probe its backend and how to build the argv for
+ * one generation child whose stdout carries a `doneRe`-matching marker line
+ * (`<marker>: done - <path> (<bytes> bytes)`) on success.
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { lastLine, run } from "./proc.mjs";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const TOOLS_ARDY = join(HERE, "..");
+const RUN_ON_BOX = join(TOOLS_ARDY, "run-on-box.sh");
+const RUN_SEQUENCE_ON_BOX = join(TOOLS_ARDY, "run-sequence-on-box.sh");
+const RUN_EDIT_ON_BOX = join(TOOLS_ARDY, "run-edit-on-box.sh");
+
+// BatchMode: never hang on a password prompt. ConnectTimeout fails fast on a
+// dead host; ServerAlive* drops a wedged connection (same set run-on-box.sh
+// uses).
+const SSH_OPTS = [
+	"-o", "BatchMode=yes",
+	"-o", "ConnectTimeout=10",
+	"-o", "ServerAliveInterval=30",
+	"-o", "ServerAliveCountMax=240",
+];
+
+export function createRemoteRunner() {
+	// Same env var names as run-on-box.sh, so health, the bases listing and
+	// generation all talk to one operator-configured host/venv/encoder.
+	const HOST = process.env.CCLAY_ARDY_HOST?.trim() || "";
+	const REMOTE = process.env.CCLAY_ARDY_REPO || "$HOME/ardy"; // literal $HOME: the REMOTE shell expands it
+	const VENV_PY = process.env.CCLAY_ARDY_VENV || "~/ardy/.venv-cuda/bin/python"; // generator venv (tilde expands on the box)
+	const ENCODER_URL = process.env.CCLAY_ARDY_ENCODER_URL || "http://127.0.0.1:9550/";
+	// Numpy-only read paths (bases listing, reference dumps) use the CPU venv
+	// on purpose: the box's two venvs are NOT interchangeable, and this is the
+	// one the dump tooling is verified under.
+	const DUMP_PY = "~/ardy/.venv/bin/python";
+
+	if (!HOST) {
+		throw new Error("CCLAY_ARDY_HOST is required for the remote runner (for example: user@ardy-host)");
+	}
+
+	// Force the same box config onto the run-*-on-box.sh wrappers even when
+	// the bridge was started with different env values; they must not disagree.
+	function boxEnv() {
+		return {
+			...process.env,
+			CCLAY_ARDY_HOST: HOST,
+			CCLAY_ARDY_REPO: REMOTE,
+			CCLAY_ARDY_VENV: VENV_PY,
+			CCLAY_ARDY_ENCODER_URL: ENCODER_URL,
+		};
+	}
+
+	// One ssh round trip covers everything health needs: the host answering is
+	// the ssh call itself, then the encoder HTTP code and the device the
+	// generator venv would pick are read on the box with the same env the
+	// generator runs under. The device line mirrors run-on-box.sh's probe
+	// exactly, so what health reports is what the generation will use.
+	function healthRemoteCmd() {
+		return [
+			`ENC="$(curl -s -o /dev/null -w '%{http_code}' -m 10 ${ENCODER_URL})"`,
+			'[ -n "$ENC" ] || ENC="000"',
+			`DEV="$(cd ${REMOTE} && ${VENV_PY} -c 'import torch; print("cuda:0" if torch.cuda.is_available() else "cpu")')"`,
+			`printf 'encoder=%s\\ndevice=%s\\n' "$ENC" "$DEV"`,
+		].join(" && ");
+	}
+
+	async function probeHealth() {
+		const { code, stdout, stderr } = await run(
+			["ssh", ...SSH_OPTS, HOST, healthRemoteCmd()],
+			{ timeoutMs: 60_000 }
+		);
+		if (code !== 0) {
+			throw new Error(`ssh probe on ${HOST} failed (exit ${code}): ${lastLine(stderr)}`);
+		}
+		const fields = {};
+		for (const line of stdout.split("\n")) {
+			const match = /^(encoder|device)=(.*)$/.exec(line.trim());
+			if (match) fields[match[1]] = match[2];
+		}
+		if (!("encoder" in fields)) {
+			throw new Error(`encoder probe on ${HOST} produced no answer`);
+		}
+		if (fields.encoder !== "200") {
+			throw new Error(`text encoder at ${ENCODER_URL} answered ${fields.encoder}, not 200`);
+		}
+		if (!("device" in fields) || fields.device === "") {
+			const tail = lastLine(stderr);
+			throw new Error(
+				`device probe on ${HOST} produced no answer${tail ? `: ${tail}` : ""}`
+			);
+		}
+		if (!/^(cpu|cuda:\d+)$/.test(fields.device)) {
+			throw new Error(
+				`device probe on ${HOST} returned unexpected ${JSON.stringify(fields.device)}`
+			);
+		}
+		return { ok: true, host: HOST, encoder: Number(fields.encoder), device: fields.device };
+	}
+
+	// Frame counts come from a real load of each npz, in ONE ssh call: the
+	// script is fed to the box's python over a quoted heredoc (no local shell
+	// step), and entries that fail to load are skipped with a note on the box
+	// stderr instead of failing the whole listing.
+	function basesRemoteCmd() {
+		const script = [
+			"import glob, json, sys",
+			"import numpy as np",
+			"entries = []",
+			'for pattern in ("outputs/*.npz", "outputs/omb/*.npz"):',
+			"    for path in sorted(glob.glob(pattern)):",
+			"        try:",
+			'            data = np.load(path, allow_pickle=False)',
+			'            frames = int(data["posed_joints"].shape[0])',
+			"            data.close()",
+			"        except Exception as exc:",
+			'            print("bases: skipping %s: %s" % (path, exc), file=sys.stderr)',
+			"            continue",
+			'        entries.append({"id": path.rsplit("/", 1)[-1][:-4], "path": path, "frames": frames})',
+			"print(json.dumps(entries))",
+		].join("\n");
+		return `cd ${REMOTE} && ${DUMP_PY} - <<'COZYCLAY_PY_EOF'\n${script}\nCOZYCLAY_PY_EOF`;
+	}
+
+	async function listBases() {
+		const { code, stdout, stderr } = await run(
+			["ssh", ...SSH_OPTS, HOST, basesRemoteCmd()],
+			{ timeoutMs: 120_000 }
+		);
+		if (code !== 0) {
+			throw new Error(`bases listing on ${HOST} failed (exit ${code}): ${lastLine(stderr)}`);
+		}
+		let entries;
+		try {
+			entries = JSON.parse(stdout);
+		} catch (err) {
+			throw new Error(
+				`bases listing on ${HOST} did not parse as JSON: ${lastLine(stderr) || err.message}`
+			);
+		}
+		if (!Array.isArray(entries)) {
+			throw new Error(`bases listing on ${HOST} was not an array`);
+		}
+		return entries;
+	}
+
+	// --- generation argv builders -----------------------------------------
+	// Each returns what the bridge needs to spawn ONE child whose stdout ends
+	// in a done marker: pose/waypoint/free single runs, autoregressive
+	// sequence runs, and context-aware motion edits.
+
+	function singleCommand({ poseFroms, basePath, prompt, durationS, seed, cpu, waypoints, rootMargin, contactThreshold, historyFrames, output }) {
+		const args = [RUN_ON_BOX];
+		for (const entry of poseFroms) {
+			args.push("--pose-from", entry.npz, String(entry.srcFrame), String(entry.dstFrame));
+		}
+		if (basePath) args.push("--base", basePath);
+		args.push("--prompt", prompt, "--duration", String(durationS));
+		if (Number.isInteger(seed)) args.push("--seed", String(seed));
+		if (cpu === true) args.push("--cpu");
+		for (const wp of waypoints || []) {
+			args.push("--root-2d", String(wp.frame), String(wp.x), String(wp.z), wp.heading === null ? "none" : String(wp.heading));
+		}
+		if (Number.isFinite(rootMargin)) args.push("--root-margin", String(rootMargin));
+		if (Number.isFinite(contactThreshold)) args.push("--contact-threshold", String(contactThreshold));
+		if (Number.isInteger(historyFrames)) args.push("--history-frames", String(historyFrames));
+		args.push("--output", output);
+		return {
+			command: "bash",
+			args,
+			env: boxEnv(),
+			doneRe: /^run-on-box: done - (.+) \((\d+) bytes\)$/,
+			label: "run-on-box",
+		};
+	}
+
+	function sequenceCommand({ segments, waypoints, seed, cpu, rootMargin, contactThreshold, historyFrames, output }) {
+		const args = [RUN_SEQUENCE_ON_BOX];
+		for (const segment of segments) {
+			args.push("--segment", segment.prompt, String(segment.durationS));
+		}
+		// Root waypoints ride the same chained rollout (rollout-global frames):
+		// the sequence generator slices the constraint set per segment call, so
+		// a path and a prompt schedule coexist.
+		for (const wp of waypoints || []) {
+			args.push("--root-2d", String(wp.frame), String(wp.x), String(wp.z), wp.heading === null ? "none" : String(wp.heading));
+		}
+		if (Number.isInteger(seed)) args.push("--seed", String(seed));
+		if (cpu === true) args.push("--cpu");
+		if (Number.isFinite(rootMargin)) args.push("--root-margin", String(rootMargin));
+		if (Number.isFinite(contactThreshold)) args.push("--contact-threshold", String(contactThreshold));
+		if (Number.isInteger(historyFrames)) args.push("--history-frames", String(historyFrames));
+		args.push("--output", output);
+		return {
+			command: "bash",
+			args,
+			env: boxEnv(),
+			doneRe: /^run-sequence-on-box: done - (.+) \((\d+) bytes\)$/,
+			label: "run-sequence-on-box",
+		};
+	}
+
+	function editCommand({ source, manifest, prompt, contextBefore, contextAfter, seed, poseNpzPaths, output }) {
+		const args = [
+			RUN_EDIT_ON_BOX,
+			"--source", source,
+			"--manifest", manifest,
+			"--prompt", prompt,
+			"--context-before", String(contextBefore),
+			"--context-after", String(contextAfter),
+			"--output", output,
+		];
+		if (Number.isInteger(seed)) args.push("--seed", String(seed));
+		for (const posePath of poseNpzPaths) args.push("--pose", posePath);
+		return {
+			command: "bash",
+			args,
+			env: boxEnv(),
+			doneRe: /^run-edit-on-box: done - (.+) \((\d+) bytes\)$/,
+			label: "run-edit-on-box",
+		};
+	}
+
+	return {
+		mode: "remote",
+		describe: () => `box ${HOST} (repo ${REMOTE}, generator venv ${VENV_PY}, encoder ${ENCODER_URL})`,
+		probeHealth,
+		listBases,
+		singleCommand,
+		sequenceCommand,
+		editCommand,
+	};
+}

package/tools/ardy/setup-local.mjs

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+/**
+ * setup-local.mjs - provision local ARDY motion generation for CozyClay.
+ *
+ *   node tools/ardy/setup-local.mjs [--skip-checkpoint] [--skip-encoder]
+ *
+ * Everything lands OUTSIDE this repo, in a per-user directory; the repo
+ * never contains model weights. All downloads come from their official
+ * sources, pinned or content-verified:
+ *
+ *   ~/.cozyclay/ardy            git clone of github.com/nv-tlabs/ardy
+ *                               (Apache-2.0) + a python venv with torch,
+ *                               ardy, gradio
+ *   HF hub cache                nvidia/ARDY-Core-RP-20FPS-Horizon40 motion
+ *                               checkpoint via huggingface_hub (NVIDIA Open
+ *                               Model License)
+ *   ~/.cozyclay/text-encoders   Llama-3-8B + LLM2Vec encoder stack from
+ *                               public, ungated mirrors, every shard
+ *                               SHA-256-verified (setup-text-encoder.py),
+ *                               then LoRA-merged in place
+ *                               (merge-text-encoder.py); ~16.4 GB, resumable
+ *
+ * Every step is idempotent: re-running verifies and fills gaps only.
+ * Overrides: CCLAY_ARDY_LOCAL_DIR, CCLAY_ARDY_ENCODERS_DIR, CCLAY_ARDY_PYTHON.
+ *
+ * torch note: `pip install torch` gives CUDA wheels on Linux and MPS wheels
+ * on Apple Silicon out of the box. On Windows, install a CUDA build first if
+ * you want GPU generation:
+ *   <venv>\Scripts\python -m pip install torch --index-url https://download.pytorch.org/whl/cu126
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const HERE = dirname(fileURLToPath(import.meta.url));
+const ARDY_GIT_URL = "https://github.com/nv-tlabs/ardy.git";
+const ARDY_CHECKPOINT = "nvidia/ARDY-Core-RP-20FPS-Horizon40";
+const LOCAL_DIR = process.env.CCLAY_ARDY_LOCAL_DIR || join(homedir(), ".cozyclay", "ardy");
+const ENCODERS_DIR = process.env.CCLAY_ARDY_ENCODERS_DIR || join(homedir(), ".cozyclay", "text-encoders");
+const IS_WIN = process.platform === "win32";
+const VENV_DIR = join(LOCAL_DIR, ".venv");
+const VENV_PY = join(VENV_DIR, IS_WIN ? "Scripts\\python.exe" : "bin/python");
+
+const skipCheckpoint = process.argv.includes("--skip-checkpoint");
+const skipEncoder = process.argv.includes("--skip-encoder");
+
+function log(message) {
+	console.log(`setup-local: ${message}`);
+}
+
+function die(message) {
+	console.error(`setup-local: ${message}`);
+	process.exit(1);
+}
+
+// Run a step to completion with output visible; die with context on failure.
+function run(label, argv, options = {}) {
+	log(label);
+	const result = spawnSync(argv[0], argv.slice(1), { stdio: "inherit", ...options });
+	if (result.error) die(`${label} failed: ${result.error.message}`);
+	if (result.status !== 0) die(`${label} failed (exit ${result.status})`);
+}
+
+function probe(argv) {
+	const result = spawnSync(argv[0], argv.slice(1), { encoding: "utf8" });
+	return result.status === 0 ? (result.stdout || "").trim() : null;
+}
+
+// --- prerequisites ----------------------------------------------------------
+
+if (!probe(["git", "--version"])) die("git is required (https://git-scm.com)");
+if (!probe(["cmake", "--version"])) {
+	die(
+		"cmake is required to build ARDY's motion-correction extension.\n" +
+			"  macOS:  brew install cmake\n" +
+			"  Linux:  apt/dnf install cmake\n" +
+			"  Windows: winget install Kitware.CMake"
+	);
+}
+
+// Python 3.10+ — ARDY's floor. Prefer an explicit override, then the newest
+// commonly-installed minor, then the bare python3.
+function findPython() {
+	const candidates = process.env.CCLAY_ARDY_PYTHON
+		? [process.env.CCLAY_ARDY_PYTHON]
+		: ["python3.12", "python3.11", "python3.10", "python3", "python"];
+	for (const candidate of candidates) {
+		const version = probe([candidate, "-c", "import sys; print('%d.%d' % sys.version_info[:2])"]);
+		if (!version) continue;
+		const [major, minor] = version.split(".").map(Number);
+		if (major === 3 && minor >= 10) return { python: candidate, version };
+	}
+	return null;
+}
+
+const found = findPython();
+if (!found) {
+	die(
+		"python 3.10+ not found (ARDY requires >=3.10).\n" +
+			"  install one (e.g. `brew install python@3.12` / `uv python install 3.12`)\n" +
+			"  or point CCLAY_ARDY_PYTHON at an interpreter"
+	);
+}
+log(`using ${found.python} (${found.version})`);
+
+// --- ARDY checkout + venv ----------------------------------------------------
+
+if (existsSync(join(LOCAL_DIR, "pyproject.toml"))) {
+	log(`ARDY checkout already present at ${LOCAL_DIR}`);
+} else if (existsSync(LOCAL_DIR)) {
+	die(`${LOCAL_DIR} exists but is not an ARDY checkout; move it aside or set CCLAY_ARDY_LOCAL_DIR`);
+} else {
+	run(`cloning ${ARDY_GIT_URL} -> ${LOCAL_DIR}`, ["git", "clone", "--depth", "1", ARDY_GIT_URL, LOCAL_DIR]);
+}
+
+if (existsSync(VENV_PY)) {
+	log(`venv already present at ${VENV_DIR}`);
+} else {
+	run(`creating venv at ${VENV_DIR}`, [found.python, "-m", "venv", VENV_DIR]);
+}
+
+function pipHas(module) {
+	return probe([VENV_PY, "-c", `import ${module}`]) !== null;
+}
+
+run("upgrading pip", [VENV_PY, "-m", "pip", "install", "--quiet", "--upgrade", "pip"]);
+if (pipHas("torch")) {
+	log("torch already installed");
+} else {
+	// Default wheels: CUDA on Linux, MPS on Apple Silicon, CPU on Windows
+	// (see the header for the Windows CUDA index-url).
+	run("installing torch (this downloads a large wheel)", [VENV_PY, "-m", "pip", "install", "torch"]);
+}
+if (pipHas("ardy")) {
+	log("ardy package already installed");
+} else {
+	// Core only — never [all]: the trt extra is Linux/CUDA-only and the demo
+	// extra is not needed for generation. The C++ extension builds here
+	// (cmake); it may fetch pybind11/Eigen/sse2neon from their upstreams.
+	run("installing ARDY into the venv (builds a small C++ extension)", [
+		VENV_PY, "-m", "pip", "install", "-e", LOCAL_DIR,
+	]);
+}
+if (pipHas("gradio")) {
+	log("gradio already installed");
+} else {
+	// Only the text-encoder *server* needs gradio; the generator's client side
+	// (gradio_client) is an ARDY core dependency already.
+	run("installing gradio (text-encoder service)", [VENV_PY, "-m", "pip", "install", "gradio"]);
+}
+
+// --- ARDY motion checkpoint (HF hub, auto-cached) ----------------------------
+
+if (skipCheckpoint) {
+	log("skipping motion checkpoint download (--skip-checkpoint)");
+} else {
+	run(`fetching motion checkpoint ${ARDY_CHECKPOINT} into the HF cache`, [
+		VENV_PY,
+		"-c",
+		[
+			"from huggingface_hub import snapshot_download",
+			`path = snapshot_download(repo_id=${JSON.stringify(ARDY_CHECKPOINT)})`,
+			"print('checkpoint at', path)",
+		].join("\n"),
+	]);
+}
+
+// --- text-encoder weights (public mirrors, SHA-256 pinned) -------------------
+
+if (skipEncoder) {
+	log("skipping text-encoder weights (--skip-encoder)");
+} else {
+	run(`downloading/verifying encoder stack under ${ENCODERS_DIR} (~16.4 GB, resumable)`, [
+		VENV_PY, join(HERE, "setup-text-encoder.py"), "--dest", ENCODERS_DIR,
+	]);
+	// Bake the MNTP LoRA into a full model (idempotent via MERGE_MANIFEST):
+	// transformers v5 cannot chase adapter dirs the way ARDY's loader expects.
+	run("merging MNTP LoRA into the base weights (one-time, needs RAM)", [
+		VENV_PY, join(HERE, "merge-text-encoder.py"), "--dest", ENCODERS_DIR,
+	], { cwd: LOCAL_DIR });
+}
+
+log("done. start CozyClay with `npm run dev` — the bridge auto-selects local mode");
+log(`  ARDY:     ${LOCAL_DIR}`);
+log(`  encoder:  ${ENCODERS_DIR} (lazy service on first generation)`);
+log("  remote box users: CCLAY_ARDY_HOST keeps selecting the ssh backend");

package/tools/ardy/setup-text-encoder-on-box.sh

@@ -0,0 +1,93 @@
+#!/usr/bin/env bash
+# setup-text-encoder-on-box.sh - provision the ARDY text-encoder models on the
+# remote box WITHOUT a Hugging Face account, gated-access approval, or token.
+#
+#   CCLAY_ARDY_HOST=user@gpu-box tools/ardy/setup-text-encoder-on-box.sh
+#   ... --verify-only     re-hash an existing tree on the box, download nothing
+#
+# Copies setup-text-encoder.py to a fresh remote temp dir (nothing is written
+# inside the ARDY checkout, same rule as run-on-box.sh), runs it with the
+# box's python3, and removes the script afterwards. The models land under
+# CCLAY_ARDY_ENCODERS_DIR (default ~/cclay-text-encoders on the box, kept
+# across re-runs; re-running only verifies and fills gaps).
+#
+# env (names shared with run-on-box.sh / sync-to-box):
+#   CCLAY_ARDY_HOST          ssh destination for the ARDY host (required)
+#   CCLAY_ARDY_ENCODERS_DIR  TEXT_ENCODERS_DIR on the box
+#                            (default $HOME/cclay-text-encoders, box-side)
+#   CCLAY_ARDY_REPO          ARDY checkout on the box (default $HOME/ardy)
+#   CCLAY_ARDY_ENC_VENV      encoder venv python on the box
+#                            (default ~/ardy/.venv/bin/python — the CPU
+#                            text-encoder venv, NOT the .venv-cuda generator)
+set -euo pipefail
+
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+HOST="${CCLAY_ARDY_HOST:-}"
+# Escaped so the REMOTE shell expands $HOME, the same trick run-on-box.sh uses.
+ENCODERS_DIR="${CCLAY_ARDY_ENCODERS_DIR:-\$HOME/cclay-text-encoders}"
+REPO="${CCLAY_ARDY_REPO:-\$HOME/ardy}"
+# Literal ~ so the REMOTE shell tilde-expands it, like run-on-box.sh's VENV_PY.
+VENV_PY="${CCLAY_ARDY_ENC_VENV:-~/ardy/.venv/bin/python}"
+
+[[ -n "$HOST" ]] || {
+  echo "setup-text-encoder-on-box: set CCLAY_ARDY_HOST (e.g. user@gpu-box)" >&2
+  exit 1
+}
+
+SSH_OPTS=(-o BatchMode=yes -o ConnectTimeout=10 -o ServerAliveInterval=30 -o ServerAliveCountMax=240)
+SCP_OPTS=(-o BatchMode=yes -o ConnectTimeout=10)
+
+if ! ssh "${SSH_OPTS[@]}" "$HOST" ":" </dev/null; then
+  echo "setup-text-encoder-on-box: cannot ssh to ${HOST}" >&2
+  exit 1
+fi
+echo "setup-text-encoder-on-box: ssh to ${HOST} ok"
+
+if ! REMOTE_TMP="$(ssh "${SSH_OPTS[@]}" "$HOST" "mktemp -d" </dev/null)"; then
+  echo "setup-text-encoder-on-box: mktemp on ${HOST} failed" >&2
+  exit 1
+fi
+[[ "$REMOTE_TMP" == /* ]] || {
+  echo "setup-text-encoder-on-box: remote mktemp returned non-absolute '${REMOTE_TMP}'; aborting" >&2
+  exit 1
+}
+trap 'ssh "${SSH_OPTS[@]}" "$HOST" "rm -rf ${REMOTE_TMP}" </dev/null >/dev/null 2>&1 || true' EXIT
+
+scp -q "${SCP_OPTS[@]}" "${HERE}/setup-text-encoder.py" "$HOST:${REMOTE_TMP}/setup-text-encoder.py"
+scp -q "${SCP_OPTS[@]}" "${HERE}/merge-text-encoder.py" "$HOST:${REMOTE_TMP}/merge-text-encoder.py"
+
+# Forward optional flags (--verify-only / --print-plan) verbatim; each one is
+# %q-quoted like every other remote arg in this toolset.
+EXTRA=""
+for arg in "$@"; do
+  EXTRA+=" $(printf '%q' "$arg")"
+done
+
+# shellcheck disable=SC2029  # ENCODERS_DIR/REMOTE_TMP expand remotely by design
+ssh "${SSH_OPTS[@]}" "$HOST" \
+  "python3 ${REMOTE_TMP}/setup-text-encoder.py --dest \"${ENCODERS_DIR}\"${EXTRA}" </dev/null
+
+# Bake the MNTP merge unless this was a flag-only run (--verify-only /
+# --print-plan download nothing, so there is nothing new to merge). The merge
+# runs inside the ARDY checkout under the encoder venv (torch + peft + the
+# ardy package) and is idempotent: it no-ops when the merged model already
+# matches the adapter hash.
+if [[ -z "$EXTRA" ]]; then
+  # shellcheck disable=SC2029  # remote expansion by design
+  ssh "${SSH_OPTS[@]}" "$HOST" \
+    "cd ${REPO} && ${VENV_PY} ${REMOTE_TMP}/merge-text-encoder.py --dest \"${ENCODERS_DIR}\"" </dev/null
+fi
+
+cat <<'EOF'
+
+setup-text-encoder-on-box: done.
+
+Restart the text-encoder service on the box with TEXT_ENCODERS_DIR set, e.g.:
+
+  ssh $CCLAY_ARDY_HOST
+  cd ~/ardy
+  TEXT_ENCODERS_DIR=$HOME/cclay-text-encoders \
+    .venv/bin/python scripts/run_text_encoder_server.py
+
+No Hugging Face login or token is needed on the box from now on.
+EOF